jackherd 0.0.1 → 1.0.1

package/kit/review/skills/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# Human-in-the-loop diagnosis loop. Last resort for Phase 1 of /diagnose, when the
+# trigger cannot be driven unattended: a device, a physical button, a native build.
+#
+# Copy it next to the investigation, fill in the four blocks, run it, and paste the
+# captured output back. The point is that a human pressing a button still produces a
+# structured, repeatable observation instead of a chat message.
+#
+# Credentials come from the environment; export them before running and redact
+# anything you paste back.
+
+set -euo pipefail
+
+readonly RUNS="${RUNS:-5}"
+readonly OUTPUT_DIR="${OUTPUT_DIR:-$(mktemp -d -t diagnose.XXXXXX)}"
+
+# The exact symptom this loop asserts. One sentence, in the user's words.
+readonly SYMPTOM='<the symptom, as the user described it>'
+
+# What the human does each round. Precise enough that two people do the same thing.
+readonly HUMAN_STEP='<the action, and what to watch for how long>'
+
+# Machine-side state captured BEFORE the human acts — evidence a restart would destroy.
+# The probes keep `|| true`: a failing probe is the signal, not an error.
+capture_before() {
+  ping -c 2 -- "${TARGET_HOST}" || true
+}
+
+# Machine-side state captured AFTER the human acts. This is what goes red or green.
+capture_after() {
+  ping -c 2 -- "${TARGET_HOST}" || true
+}
+
+if [[ -z "${TARGET_HOST:-}" ]]; then
+  echo 'TARGET_HOST is not set — export it before running (the probes need a target).' >&2
+  exit 1
+fi
+
+mkdir -p -- "${OUTPUT_DIR}"
+
+for run in $(seq 1 "${RUNS}"); do
+  log="${OUTPUT_DIR}/run-${run}.log"
+
+  {
+    echo "=== run ${run}/${RUNS} ==="
+    echo "symptom: ${SYMPTOM}"
+    echo "--- before ---"
+    capture_before
+  } >>"${log}" 2>&1
+
+  printf '\n[run %s/%s] %s\n' "${run}" "${RUNS}" "${HUMAN_STEP}"
+  printf 'Did the symptom occur? [y/n/q] '
+  read -r verdict </dev/tty
+
+  case "${verdict}" in
+    q) break ;;
+    y) echo "verdict: RED" >>"${log}" ;;
+    *) echo "verdict: green" >>"${log}" ;;
+  esac
+
+  {
+    echo "--- after ---"
+    capture_after
+  } >>"${log}" 2>&1
+done
+
+echo
+echo "Captured ${OUTPUT_DIR}"
+grep -h '^verdict:' "${OUTPUT_DIR}"/run-*.log | sort | uniq -c
+echo 'Reproduction rate below ~50% is not yet debuggable — raise it before Phase 2.'

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

@@ -0,0 +1,100 @@
+---
+name: pre-commit
+description: 'Pre-Commit Orchestrator — detects changed files, routes to the right reviewers, suggests commit message.'
+---
+
+If `.claude/project/pre-commit.md` exists, read it first. It extends this skill for this project (extra judgement checks, post-deploy reminders) and wins where the two disagree.
+
+You are the **Pre-Commit Orchestrator**. You measure what a command can measure, route the change to the reviewers that judge the rest, and ask the user for the commit.
+
+## Step 1: Run the deterministic checks
+
+```bash
+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`.
+
+**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.
+
+`--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.
+
+## Step 3: Specialized Reviewers
+
+**Step 1 printed the reviewer list** (`Reviewers: …`, from `check.reviewerRoutes`) — 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.
+- 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.
+
+**`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.
+
+## 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 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.
+
+## Step 6: arc42 Check
+
+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.
+
+## Output Format
+
+Write the summary in {{kit.responseLanguage}}:
+
+```
+## Pre-Commit Review
+
+Changed files: [file list]
+Active reviewers: Review + Spec + [routed reviewers]
+
+### Deterministic checks: PASS / FAIL
+[the result lines of `jh check`, with the failing detail. Numbers, not impressions]
+
+### Code Quality: PASS / FIX FIRST
+### [reviewer name]: PASS / FAIL
+[findings, one paragraph per reviewer]
+
+### Generated Files: ✅ / ❌
+### Spec: PASS / PASS WITH NOTES / FAIL / N/A
+### arc42: ✅ checked / ⚠️ update recommended (question follows)
+### Architecture (ARCHITECTURE.md): ✅ checked / ⚠️ update recommended (question follows) / N/A
+
+### 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.
+
+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.
+
+## 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.
+
+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:
+
+```bash
+git add -- "<path from step 1>" "<path from step 1>"
+```
+
+```bash
+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.

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

@@ -0,0 +1,43 @@
+---
+name: review
+description: 'Code Quality Review — the judgement checks over changed files that no command decides. Use after any code change before committing.'
+---
+
+If `.claude/project/review.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
+
+You are the **Reviewer** — you judge what a command cannot. Architecture and design are `/uncle-bob`'s job.
+
+## Measurements first
+
+```bash
+bunx jackherd check
+```
+
+Types, lint, unused imports, staged build artifacts and failing tests are decidable, and this command decides them. **Quote its output; the verdict on those points is the command's.** A verdict you could not measure is a guess, and the guess that costs is the confident false PASS. When invoked from `/pre-commit` the command has already run — take that output instead of running it twice.
+
+## Checks that need judgement
+
+1. **Dead code**: unused exports, unreachable branches, commented-out leftovers
+2. **Naming**: does the name reveal intent, or does it need a comment to explain what it holds
+3. **Function size**: anything past ~20 lines, or a description that needs an "and"
+4. **Duplication**: more than three lines of identical logic in two places
+5. **Design review**: the checklist in `.claude/rules/kit/code-style.md` → Design Review
+
+## Output Format
+
+In {{kit.responseLanguage}}:
+
+```
+## Code Quality Review
+
+Measured (jh check): PASS / FAIL
+[the failing lines, verbatim]
+
+1. Dead code:     ✅ / ❌
+2. Naming:        ✅ / ❌
+3. Function size: ✅ / ❌
+4. Duplication:   ✅ / ❌
+5. Design review: ✅ / ❌
+
+Verdict: PASS / FIX FIRST
+```

package/kit/review/skills/security-audit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: security-audit
+description: 'Use when a change touches auth, tenant isolation, access policies, API keys, secrets, user input, database queries, message payloads or infrastructure: OWASP Top 10, secrets exposure, authz, input validation, injection, path traversal.'
+---
+
+If `.claude/project/security-audit.md` exists, read it first. It adds this project's security checks (its database's access policies, its tenant model, its known incidents) and wins where the two disagree.
+
+You are a Security Engineer: paranoid, systematic, every finding carries its evidence.
+
+You receive a `git diff` or a list of changed files. Read the relevant files and review through these lenses.
+
+> **Why the name.** This skill is `security-audit`, not `security-review`, because Claude Code ships a
+> built-in skill of that name. A project skill sharing it would leave which one `/security-review`
+> reaches undecided. Review gates name `/security-audit`.
+
+## Checks
+
+### Secrets & Credentials
+
+1. No hardcoded secrets: API keys, passwords, tokens live in environment variables or the secret store.
+2. No secret logging: credentials stay out of logs, error messages and terminal output.
+3. Secret files stay out of git: `.env`, `.env.local`, `*.pem`, `*.key`.
+
+### Authentication & Authorization
+
+4. Access policies: every table with user data is protected by the database's access policies (row-level security where the database has it).
+5. Tenant isolation: in a multi-tenant system, every query and every message is scoped by tenant. No cross-tenant reads or writes.
+6. API key validation: new endpoints sit behind the auth middleware.
+7. Token validation: tokens are verified (signature, expiry, issuer), never only decoded.
+8. Policy cost: a policy compares a claim from the token against a column; a per-row lookup into the user table is unsargable and can take a database down under load.
+
+### Input Validation
+
+9. Schemas at system boundaries: every external input (HTTP body, message payload, webhook) is validated with a schema.
+10. SQL injection: queries are parameterized; user input never reaches query text through string interpolation.
+11. Path traversal: a user- or config-controlled file path is normalised and checked to stay inside its base directory, symlinks included.
+12. XSS: user input never reaches HTML unescaped.
+
+### Write Paths
+
+13. No `upsert` on a generated natural key: a conflict target the caller does not own turns a replayed identifier into a write into someone else's row. Create and update are separate statements, and an update is scoped by tenant as well as by key (`.claude/rules/kit/code-style.md` → Database Writes).
+14. Generated identifiers carry entropy, not a clock.
+
+### Dependencies & Supply Chain
+
+15. New dependencies: check for known CVEs. Is it actually needed?
+16. Excessive permissions: new packages with native binaries, network calls at install, or `postinstall` scripts.
+
+### Messaging
+
+17. Message handlers validate the payload before processing.
+
+## Your Output Format
+
+In {{kit.responseLanguage}}. For each finding:
+
+```
+[SEVERITY] Category — File:Line
+Description of the issue
+→ Recommended fix
+```
+
+Severities: CRITICAL, HIGH, MEDIUM, LOW, INFO
+
+At the end a summary: findings per severity, overall verdict (**PASS** / **PASS WITH NOTES** / **FAIL**).

package/kit/review/skills/uncle-bob/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: uncle-bob
+description: 'Clean Architecture Review — SOLID, Dependency Direction, Small Functions. Use for backend and service code review.'
+---
+
+If `.claude/project/uncle-bob.md` exists, read it first. It adds this project's architecture checks (event patterns, service boundaries, where domain types live) and wins where the two disagree.
+
+You are **Uncle Bob** — Clean Architecture, SOLID, small functions.
+
+## Checks
+
+1. **Single Responsibility**: Every function/module does exactly one thing. Does the description need an "and"? Then split it. In a diff this shows up as *divergent change* — one file edited for several unrelated reasons. → split so each module changes for one reason.
+2. **DRY**: No copy-pasted logic. More than 3 identical lines in two places → shared helper.
+3. **Dead Code**: Unused exports, unreachable branches, commented-out code → remove them.
+4. **Naming**: Names reveal intent. If a comment is needed to explain what a variable holds → rename it.
+5. **Small Functions**: Functions > ~20 lines are a smell. Extract sub-steps into named helpers.
+6. **Dependency Direction**: Pure utilities never import side-effectful modules. Arrows point inward.
+7. **No Flag Arguments**: Booleans that switch behavior → split into two functions.
+8. **Error Surface**: Only handle errors that are meaningfully recoverable. Let the rest propagate.
+9. **Data Clumps**: The same few fields or parameters keep travelling together — a type wanting to be born. → bundle them into one type and pass that.
+10. **Primitive Obsession**: A `string`, `number` or raw record standing in for a domain concept. → give the concept its own small type, usually a schema with an inferred type.
+11. **Shotgun Surgery**: One logical change forces scattered edits across many files in the diff. → gather what changes together into one module. The inverse of divergent change in check 1.
+12. **Speculative Generality**: Abstraction, parameters, slots or hooks added for a need nothing in the diff has. → delete it and inline back until a real second caller shows up.
+
+Checks 9 to 12 are **labelled heuristics, never hard violations** — report them as "possible Data Clump", with the call left to the author. Skip anything the linter already enforces, and skip anything a documented rule in `.claude/rules/` explicitly endorses: the rules win over this list.
+
+### Additional Checks
+
+- **Code Order**: Types → pure functions → higher-order functions (`.claude/rules/kit/code-style.md`).
+- **Framework as adapter**: domain logic lives in framework-free modules (`.claude/rules/kit/code-style.md`).
+
+## Your Output Format
+
+In {{kit.responseLanguage}}. For each violation:
+
+- **Rule** (which of the 12 points)
+- **File + line**
+- **Problem** (one sentence)
+- **Fix** (concrete proposal)
+
+At the end: overall verdict (PASS / PASS WITH NOTES / FAIL).
+
+If everything is clean, just say: "Clean. Ship it."

package/kit/rules/rules/kit/arc42.md

@@ -0,0 +1,89 @@
+---
+paths:
+  - "docs/architecture/**"
+---
+
+# arc42 Architecture Documentation
+
+Single source of truth for the architecture documentation in `docs/architecture/`. Skills (`/plan`, `/implement`, `/pre-commit`) reference this file for the arc42 filter.
+
+Reference model: [arc42.org/overview](https://arc42.org/overview). arc42 defines 12 sections; maintain a **subset** — only what delivers real value. Empty sections stay out.
+
+> **Output language: {{kit.planLanguage}}.** These instructions are English; the documents in
+> `docs/architecture/` are written in {{kit.planLanguage}}, like plans and ADRs.
+
+## Core Principle: derive from the code
+
+Architecture documentation is derived **after** the implementation from the finished code. Exception: an ADR accompanying a plan records a decision as soon as it is made — before implementation, with `Status: Proposed`.
+
+**Planned ≠ built.** Document only built code as real. Mark building blocks, systems and flows that are not yet implemented explicitly as planned, with a link to the plan in `{{kit.planDirectory}}/`, and ADRs with `Status: Proposed`. A reader must be able to tell what exists and what is the target picture without looking at the code.
+
+## Section Mapping
+
+| File | arc42 section | Content |
+| ---- | ------------- | ------- |
+| `01-context.md` | 3 — Context & scope | External systems, interfaces, direction, protocol |
+| `05-building-blocks.md` | 5 — Building block view | Static decomposition into levels (whitebox) |
+| `06-runtime.md` | 6 — Runtime view | Significant flows as sequence/state diagrams |
+| `08-concepts.md` | 8 — Cross-cutting concepts | Reusable patterns (auth, events, tracing, data access) |
+| `09-decisions.md` | 9 — ADRs | Architecture decisions, numbered chronologically |
+
+Create further sections (deployment, solution strategy, quality, risks, glossary) only when a plan shows real value for them.
+
+## arc42 Filter — which change hits which section?
+
+On at least one hit: **ask the user concretely** (see ask workflow).
+
+| Criterion | Section | Update when… |
+| --------- | ------- | ------------ |
+| New external system, API, hardware, service | `01-context.md` | An integration with a new system is implemented |
+| New app / service / package | `05-building-blocks.md` | A new service or package was created |
+| New significant flow | `06-runtime.md` | A new lifecycle step, replication strategy, event flow |
+| New cross-cutting concept or pattern | `08-concepts.md` | A pattern applied in several places |
+| Architectural decision (A vs. B, not obvious) | `09-decisions.md` | A decision that permanently constrains the solution space |
+
+**No hit** (no update, no follow-up question) for: bug fixes, styling, small UI tweaks, pure refactorings without decision character.
+
+## Ask Workflow
+
+On a hit, ask concretely and with context, in {{kit.responseLanguage}} — never a generic "update the docs?". Name the change, the section, and why it qualifies:
+
+> "The union type for the selector shapes every call site permanently — an API decision. Shall I add
+> an ADR to `docs/architecture/09-decisions.md`?"
+
+On "yes": add a concrete task to the plan's `## {{kit.heading.documentation}}` section, or write the section directly. For multi-phase plans, schedule the arc42 derivation as the last phase.
+
+## Building Block View (05) — levels
+
+The building block view is **hierarchical**. Every level is a whitebox: an overview diagram, the contained building blocks, and the important interfaces.
+
+- **Level 1 — whitebox of the overall system (mandatory):** a `graph TB` overview of the topmost building blocks, plus tables of the contained packages, apps and services, each with one responsibility.
+- **Level 2 — whitebox of selected building blocks:** decompose important ones further (a service into handler → use-cases → adapter), only where the complexity justifies it.
+- **Level 3:** only on real demand.
+
+One coarse overview diagram plus detail diagrams for complex subsystems. A 30-node graph is unreadable.
+
+## Runtime View (06)
+
+One `sequenceDiagram` **per significant flow**; state machines as `stateDiagram-v2`. Document only flows that are not trivially readable from the code.
+
+## Cross-cutting Concepts (08)
+
+A concept is a pattern that applies in **several** places. Data model tables plus a short description of the rule. Not a feature-by-feature log.
+
+## Decisions (09) — ADR format
+
+Numbered chronologically (`ADR-001`, `ADR-002`, …). Existing ADRs stay as written — new ones go on top, an old one is marked `Status: Superseded by ADR-NNN` when needed. Every ADR carries: date, status (`Proposed | Accepted | Superseded by ADR-MMM`), context (why the question arises, which options), decision, rationale (error cost, constraints, trade-offs), consequences (what follows, the accepted price).
+
+The source for ADRs are the `## {{kit.heading.decisions}}` tables of the plans in `{{kit.planDirectory}}/`.
+
+## Diagram Convention: Mermaid
+
+All diagrams as **Mermaid** in markdown code blocks. GitHub and editors render it natively.
+
+| Section | Mermaid type |
+| ------- | ------------ |
+| `01-context.md` | `C4Context` (or `graph LR`) |
+| `05-building-blocks.md` | `graph TB` (overview + detail per subsystem) |
+| `06-runtime.md` | `sequenceDiagram` (one flow per diagram) |
+| `08-concepts.md` | `stateDiagram-v2` (state machines) |

package/kit/rules/rules/kit/architecture-files.md

@@ -0,0 +1,87 @@
+---
+paths:
+  - "services/**"
+  - "packages/**"
+  - "**/ARCHITECTURE.md"
+---
+
+# ARCHITECTURE.md — Durable Architecture Contracts
+
+Single source of truth for `ARCHITECTURE.md` files next to services and domain packages. Skills (`/plan`, `/implement`, `/pre-commit`) reference this file for the filter.
+
+> **Not the same thing as `docs/architecture/`.** `docs/architecture/` (arc42, see `arc42.md`)
+> documents the system as a whole. `ARCHITECTURE.md` is module-level: what one service or package
+> promises about itself. A decision that spans several services belongs in the ADRs; a fact only
+> this unit knows about itself belongs here.
+
+## Core Principle: state, not change
+
+| Artifact | Question | Lifecycle |
+| -------- | -------- | --------- |
+| `README.md` | How do I run this? | Updated ad hoc |
+| `{{kit.planDirectory}}/*.md` | How do we get from current to target? | Archived once done |
+| `ARCHITECTURE.md` | What must stay true going forward? | Updated in place, never archived |
+
+`ARCHITECTURE.md` holds what only this service or package knows about itself: ownership, invariants, and trade-offs deliberately accepted. Conventions for every service belong in a rule, the system view in `docs/architecture/`.
+
+## Template
+
+```markdown
+# Architecture — <path>
+
+<One-sentence scope.>
+
+## Owns
+
+- <table/topic/route this unit is the exclusive writer of>
+
+## Reads, does not own
+
+- <data it reads but another unit owns>
+
+## Invariants
+
+| Invariant | Why |
+| --- | --- |
+
+## Known accepted risks
+
+| Risk | Status | Source |
+| --- | --- | --- |
+```
+
+Language: English, like `README.md` — `ARCHITECTURE.md` lives next to code.
+
+## Filter — which change touches an ARCHITECTURE.md?
+
+On at least one hit: **ask the user concretely**, the same discipline as the arc42 filter.
+
+| Criterion | Update when… |
+| --------- | ------------ |
+| New service or package created | Create the initial `ARCHITECTURE.md`, **if it clears the bar below** |
+| Ownership boundary changes | A table/topic/route starts or stops being exclusively written by this unit |
+| A deliberate trade-off is decided | A review finding is accepted rather than fixed, or a plan decision records a permanent constraint scoped to one unit |
+| An invariant is introduced whose silent violation would be a bug, not a crash | Null-vs-zero distinctions, ordering guarantees, exactly-once/dedup guarantees, "field X is set once and never recalculated" |
+| A schema migration adds a non-obvious backfill or version rule | A nullable field needs an explicit backfill; a version bump and its migration must land in one edit |
+
+**No hit** for: bug fixes without a new invariant, styling, pure refactorings, dependency bumps.
+
+### Not every package needs one
+
+A package earns the file when it has at least one of:
+
+- **global or process-wide state** it claims (patching `console.*`, a singleton connection),
+- an **ownership boundary** other units must respect (event subjects, a table only it writes),
+- an **invariant whose silent violation is a bug, not a crash**.
+
+A presentation package whose contract is "these are the components and their props" does not. When in doubt, ask rather than create; an empty `ARCHITECTURE.md` reads as "nothing to know here".
+
+## Ask Workflow
+
+On a hit, ask concretely and with context, in {{kit.responseLanguage}} — never a generic "update the architecture file?":
+
+> "`invoice_lines.id` is now taken over from the client as primary key instead of being assigned by
+> the server. That is an accepted risk, not a bug. Shall I add it to `services/billing/ARCHITECTURE.md`
+> under 'Known accepted risks'?"
+
+On "yes": add a concrete task to the plan's `## {{kit.heading.documentation}}` section, or write the file directly for a small, single-phase change.

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

@@ -0,0 +1,159 @@
+# 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.
+
+## Formatting
+
+The formatter and linter config is the authority; these are the conventions it encodes:
+
+- Single quotes, no semicolons, 2-space indent, trailing commas.
+- Sorted imports; no unused imports.
+- Arrow functions over `function` declarations.
+- Template literals over string concatenation.
+- Blank lines separate logical sections; decorative separator comments (`// ─────────`) stay out.
+
+## 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}}.
+
+## 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.
+
+## 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 JSDoc
+
+Add JSDoc 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)
+- 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.
+
+## Code Organization
+
+**Follow this order strictly:**
+
+1. **Types first**: interfaces, types, type aliases at the top (after imports)
+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.
+
+- **Domain logic lives in framework-free `.ts` 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.
+
+## Code Reuse
+
+**Before implementing new functionality:**
+
+1. **Search the codebase** for existing utilities, helpers, components and services.
+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.
+
+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.
+
+## 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.
+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.
+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.
+
+Apply these checks to **your own output** before presenting it, and fix violations right away.
+
+## Generators
+
+Before editing a file that might be generated:
+
+1. **Check `package.json` scripts** 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`.
+- 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()`).
+
+### 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.
+
+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.
+
+```ts
+// ✅ 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 =>
+  (Object.values(FEE_MODE) as string[]).includes(value)
+
+if (isFeeMode(id)) handleChange(switchMode(form, id))
+
+// ❌ unchecked literal at the seam, and a default nobody chose
+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.
+
+## 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.
+
+- **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 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.
+
+### 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.
+
+## 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.