@kiwidata/grimoire 0.1.3 → 0.1.4

package/skills/references/adversarial-personas.md

@@ -0,0 +1,225 @@
+# Adversarial Personas Reference
+
+Loaded by `grimoire-review`, `grimoire-pr-review`, and `grimoire-precommit-review` when the change touches a user-facing surface. Defines the surface-conditional adversarial personas that complement the engineering / product / security personas in `./review-personas.md`.
+
+Each persona inhabits a user the design might fail. Their job is to find the failure paths a happy-path-focused reviewer would miss: the keyboard-only user who can't tab to the submit button, the screen-reader user lost in an unlabelled icon grid, the user on a 3G connection waiting for a 4 MB hero image.
+
+The set engaged on a given review is filtered by `project.surface` (see §Activation Matrix). All personas inherit the project briefing (§1 of `./review-personas.md`), the materiality gate (§2), and the steel-man requirement (§2a).
+
+---
+
+## Persona Catalog
+
+Each persona below names: **identity** (whose constraints they hold), **evaluation criteria** (what they look at), **what triggers a finding** (the concrete observation that becomes feedback).
+
+### Keyboard-Only User
+
+- **Identity**: Power user navigating exclusively via keyboard (Tab, Shift-Tab, arrow keys, Enter, Esc). Mouse unavailable due to RSI, motor impairment, terminal-only environment, or preference for speed.
+- **Evaluation criteria**:
+  - Every interactive element reachable via Tab in a sensible order
+  - Focus indicator visible on every focusable element
+  - No keyboard traps (except modal dialogs, which must escape on Esc)
+  - Shortcuts documented and consistent (don't shadow OS / browser defaults)
+  - Custom controls (combobox, datepicker, drag-drop) implement full keyboard interaction patterns per WAI-ARIA Authoring Practices
+- **Triggers a finding**:
+  - Click-only handler without keyboard equivalent
+  - Focus indicator suppressed (`outline: none` without replacement)
+  - Tab order jumps visually unrelated regions
+  - Modal dialog cannot be dismissed with Esc
+  - Custom dropdown reachable but not operable from keyboard
+
+### Screen-Reader User
+
+- **Identity**: User of VoiceOver (macOS/iOS), NVDA (Windows), JAWS (Windows), or TalkBack (Android). Navigates by reading aloud announcements; relies on semantic markup and ARIA.
+- **Evaluation criteria**:
+  - Semantic HTML used in preference to ARIA (`<button>` not `<div role="button">`)
+  - Every form input has a programmatically-associated label
+  - Icons that convey meaning have accessible names (`aria-label` or visually-hidden text)
+  - Dynamic content changes are announced (live regions or focus shifts)
+  - Heading hierarchy is meaningful (H1 once, H2 sections, no skipped levels)
+  - Image alt text describes meaning, not appearance (decorative images: `alt=""`)
+- **Triggers a finding**:
+  - Icon-only button without accessible name
+  - Form field with placeholder used as the only label
+  - Live error announcement missing (form submit → silent failure)
+  - Decorative SVG read aloud as a long filename
+  - `<div onclick>` instead of `<button>`
+
+### Low-Vision / Color-Blind User
+
+- **Identity**: User with low vision (uses browser zoom 200%+, OS magnifier), or color vision deficiency (deuteranopia, protanopia, tritanopia, monochromacy — affects ~8% of men, ~0.5% of women).
+- **Evaluation criteria**:
+  - Body text contrast ≥ 4.5:1 (WCAG AA)
+  - UI component contrast ≥ 3:1 vs adjacent
+  - Information not conveyed by color alone (status badges have icons or text; error fields have text labels not just red borders)
+  - Page reflows cleanly at 200% zoom (no horizontal scroll, no overlapping content)
+  - Text scales when user adjusts browser font size (no fixed `px` font sizes on body text where `rem` would work)
+- **Triggers a finding**:
+  - Gray text on white below 4.5:1 (the perennial offender)
+  - Red/green status indicator with no icon or text differentiator
+  - Layout breaks at 200% zoom (content cut off, controls overlap)
+  - Required-field marker conveyed only by red asterisk color (no actual asterisk character)
+
+### Touch-Target User
+
+- **Identity**: Mobile user, often one-handed, often with imprecise thumb input (in motion, accessibility-impaired motor control, or just normal use on a small screen).
+- **Evaluation criteria**:
+  - Interactive targets ≥ 24×24 CSS pixels (WCAG 2.2 AA minimum); ≥ 44×44 preferred (iOS HIG)
+  - 8px+ spacing between adjacent targets
+  - Primary actions reachable in the thumb zone (bottom half of phone screen)
+  - No hover-only affordances (hover doesn't exist on touch)
+  - Long-press, swipe, pinch interactions have a tap-only equivalent
+- **Triggers a finding**:
+  - Buttons sized below 24×24 in the actual rendered design
+  - Adjacent links in a list with no spacing (mis-tap risk)
+  - Primary CTA in the top-right corner (unreachable for one-handed use on large phones)
+  - Tooltip is the only source of help text on a touch surface
+
+### Responsive-Breakpoint User
+
+- **Identity**: User on a viewport the designer didn't focus-test — 320px-wide phones, foldables in their open state, 5K desktops, browser windows the user resized.
+- **Evaluation criteria**:
+  - Layout works from 320px viewport width upward (smallest common phone)
+  - No horizontal scroll except for content where scrolling is intentional (tables, code blocks)
+  - Breakpoints handle landscape phone orientation (short, wide viewports)
+  - Text remains readable line length (45-75 characters) across breakpoints — does not stretch to full ultra-wide width
+  - Touch targets remain ≥ 24×24 at the smallest breakpoint
+- **Triggers a finding**:
+  - Card layout breaks below 360px (content overflows or overlaps)
+  - Sidebar that collapses to a hamburger but the hamburger button is itself 12×12
+  - Line length unconstrained on ultra-wide displays (text spans 2000px)
+  - Modal dialog wider than the viewport, requiring horizontal scroll inside the modal
+
+### RTL / i18n User
+
+- **Identity**: User of a right-to-left script (Arabic, Hebrew, Persian, Urdu) or a language with different text expansion (German, Finnish — typically 30% longer; Chinese, Japanese, Korean — often shorter but with line-break rules).
+- **Evaluation criteria**:
+  - Layout mirrors correctly under `dir="rtl"` (logical properties used: `margin-inline-start` not `margin-left`)
+  - Icons that imply direction (arrows, chevrons) flip; icons that don't (clock, magnifying glass) don't
+  - Strings interpolated with placeholders use named/positional substitution, not concatenation
+  - Hardcoded strings flagged; user-visible text comes from a translation catalog
+  - Date, number, currency formats use the user's locale
+- **Triggers a finding**:
+  - User-visible string hardcoded in the markup (not extracted for translation)
+  - Layout breaks visually under `dir="rtl"` (margins on the wrong side, icons not mirrored)
+  - Date displayed as `MM/DD/YYYY` without locale awareness (ambiguous globally)
+  - String concatenation that won't translate cleanly: `"You have " + count + " items"` → use a translation function with placeholders
+
+### Low-Bandwidth / Offline User
+
+- **Identity**: User on slow or intermittent network (3G, congested wifi, satellite, train tunnel). Frequent in markets the project may not actively target but where users still exist.
+- **Evaluation criteria**:
+  - Total payload weight for first meaningful render reasonable for the surface (web < 200 KB JS gzipped is a starting bar; mobile native should function offline-first for read paths)
+  - Images sized to actual display dimensions; modern formats (AVIF, WebP) with fallbacks
+  - Network failures fail gracefully (cached state, queued writes, retry with backoff)
+  - Loading states address slow connections, not just fast ones (skeleton at 100ms, escalated message at 5s)
+- **Triggers a finding**:
+  - Hero image > 1 MB without responsive `srcset`
+  - Form submit hangs indefinitely when network is dropped (no timeout, no queue)
+  - Critical content loaded via blocking JS bundle > 500 KB
+  - No offline state — app crashes or shows blank screen when network is lost
+
+### Hostile Actor
+
+- **Identity**: User actively trying to misuse the design — abuse a flow, exfiltrate data, deceive other users via the system, or weaponize the UI as part of a social-engineering attack. Adversarial UX, not just adversarial security.
+- **Evaluation criteria**:
+  - User-generated content is escaped and rendered safely (no XSS, no markdown that smuggles HTML)
+  - Rate limits visible to legitimate users (so they understand why an action was blocked) but unbypassable
+  - Sharing / impersonation features have abuse mitigation (report button, mute, block)
+  - Display-name fields don't accept Unicode lookalikes that impersonate other users (homograph attack)
+  - Email / SMS templates can't be hijacked for phishing-by-proxy (user-supplied URL appearing in an authority-branded message)
+  - Sensitive actions require recent re-authentication, not just an open session
+- **Triggers a finding**:
+  - Comment field renders user-supplied HTML
+  - Search field reflects input back into the page without escaping
+  - Profile URL accepts `javascript:` scheme
+  - "Invite via email" feature sends arbitrary user-supplied text from the project's domain
+
+### API Conventions Reviewer
+
+- **Identity**: API consumer (internal team, partner, third-party developer). Evaluates the *design* of public APIs the same way users evaluate UI — for consistency, predictability, and minimum surprise.
+- **Evaluation criteria**:
+  - REST: resource-oriented URLs, correct HTTP verbs and status codes, consistent error envelope, predictable pagination
+  - GraphQL: schema follows naming conventions (camelCase fields, PascalCase types), no over-fetching defaults, deprecation flow uses `@deprecated` not removal
+  - Idempotency: PUT and DELETE are idempotent; POST that should be idempotent uses an `Idempotency-Key` header
+  - Versioning: breaking change has a versioning plan (URL path, header, or media type — but consistent across the API)
+  - Discoverability: spec is published (OpenAPI, GraphQL introspection); errors point to docs
+- **Triggers a finding**:
+  - New `POST /deleteUser` endpoint (verb in URL — should be `DELETE /users/:id`)
+  - Inconsistent error envelopes across endpoints (some `{ error: "..." }`, some `{ message: "..." }`)
+  - Breaking change to a documented field with no version bump or deprecation notice
+  - 200 OK returned for an operation that failed (status code masks the error)
+
+---
+
+## Activation Matrix
+
+Engagement of each persona is determined by `project.surface`. The matrix below comes from ADR-0019.
+
+| Persona | TUI | Web | Mobile | API | Mixed |
+|---|---|---|---|---|---|
+| Keyboard-only | required | required | n/a | n/a | required |
+| Screen-reader | n/a | required | required | n/a | required |
+| Low-vision / color-blind | n/a | required | required | n/a | required |
+| Touch-target | n/a | n/a | required | n/a | required |
+| Responsive-breakpoint | n/a | required | n/a | n/a | required |
+| RTL / i18n | conditional | conditional | conditional | n/a | conditional |
+| Low-bandwidth / offline | n/a | required | required | conditional | required |
+| Hostile actor | required | required | required | required | required |
+| API conventions | n/a | n/a | n/a | required | required |
+
+**Legend**:
+- **required** — persona engages by default on this surface
+- **conditional** — persona engages only when a project briefing axis flags it (e.g., `i18n` tag has count > 0 in the feature inventory; project compliance includes a region requiring RTL)
+- **n/a** — persona does not engage by default; user can still invoke via `--personas=...`
+
+**User override always available** via `--personas=keyboard,low-vision` or "skip <persona>". Surface is the default; the user is the override.
+
+**Mixed surface** runs the union of all surface-specific personas. Projects that genuinely span TUI + web + mobile should set `surface: mixed`; that is the cost of breadth.
+
+**Unknown surface** (config field absent) falls back to `mixed`. Better to over-engage than to silently skip critical personas.
+
+---
+
+## Materiality Gate Cross-Reference
+
+Every adversarial finding must cite an axis from the Project Briefing (§1 of `./review-personas.md`). The adversarial set extends the briefing axes the original engine considered:
+
+- **Surface axis** (this engine adds it) — TUI vs web vs mobile vs API determines which personas engage at all
+- **Brand axis** — if `.grimoire/brand/tokens.json` defines a contrast ratio target, the low-vision persona uses it; otherwise WCAG AA default
+- **Compliance axis** — `project.compliance` mentions WCAG, ADA, EAA (European Accessibility Act), Section 508 → screen-reader and low-vision findings escalate from suggestion to blocker by default
+- **Threat-surface tags** (existing) — `i18n=N` count > 0 promotes RTL persona from conditional to required; `mobile=N` count > 0 promotes touch-target persona
+
+A finding from any persona below that lacks a briefing anchor is dropped. The full materiality rules from `./review-personas.md` §2 apply unchanged.
+
+---
+
+## Steel-Man Requirement
+
+Per `./review-personas.md` §2a, every adversarial finding must include a steel-man before submission:
+
+- **Steel-man**: "The designer likely chose this because <strongest plausible reason — convention, performance, scope, stage>."
+- **Why it still fails**: "Despite that, <concrete harm path tied to a briefing axis — named user impacted, named state, named consequence>."
+
+If either line cannot be completed with substance, the finding is dropped. "An accessibility issue" is not a finding; "screen-reader user submitting the login form receives no audible feedback on validation error — they cannot recover without sighted assistance" is a finding.
+
+Vague harm paths fail this gate. The adversarial personas exist precisely to name specific harms; generic ones are noise.
+
+---
+
+## Severity Calibration
+
+The default for an adversarial finding is **suggestion**. A finding is a **blocker** when *all three* hold (mirroring `./review-personas.md` §2b):
+
+1. **Concrete harm path** — named user (the persona), named trigger, named consequence
+2. **Briefing-anchored** — the consequence threatens a briefing axis (surface, compliance, brand contrast target, threat-surface tag)
+3. **Not already mitigated** — neighbor code, design-system component, or sibling feature does not already handle it
+
+Adversarial-specific severity rules:
+
+- WCAG AA violations on a project that lists WCAG / ADA / EAA in `project.compliance` → blocker by default (regulator anchor)
+- Deceptive patterns (see `./design-heuristics.md` §3) → blocker by default on customer-facing stage; suggestion on internal-tools stage
+- Hostile-actor findings with a working harm path → blocker, regardless of stage (security overlap)
+- Touch-target findings on a mobile surface where the project ships → blocker if a user couldn't complete a primary task; suggestion if it's a secondary control
+
+Zero findings is a valid outcome. A persona that returns "no material findings under the briefing" is doing its job. The Contrarian pass (§4.8 of `./review-personas.md`) calibrates inflated findings post-hoc.

package/skills/references/brand-tokens-format.md

@@ -0,0 +1,186 @@
+# Brand Tokens Format Reference
+
+Loaded by `grimoire-design` (variant generation, lint mode) and any review skill running visual-fidelity checks. Defines the on-disk shape of `.grimoire/brand/tokens.json` and the voice/tone file beside it.
+
+The format is **W3C Design Tokens (DTCG) JSON** — an emerging standard supported by Tokens Studio (Figma plugin), Style Dictionary (compiler), and design-extract (URL scraper). See ADR-0016 for the format decision.
+
+---
+
+## File Layout
+
+```
+.grimoire/brand/
+  tokens.json     # DTCG-format design tokens (colors, typography, spacing, etc.)
+  voice.md        # Markdown voice/tone — DTCG does not cover prose
+```
+
+`brand_dir` in `.grimoire/config.yaml` can override the location; default is `.grimoire/brand`.
+
+---
+
+## DTCG Basics
+
+Every leaf token is an object with `$value` and `$type`. Optional `$description` documents intent. Nesting creates groups.
+
+```json
+{
+  "color": {
+    "primary": {
+      "$value": "#0066ff",
+      "$type": "color",
+      "$description": "Brand primary — links, primary buttons, focus rings"
+    }
+  }
+}
+```
+
+Group nodes (objects without a `$value`) carry no metadata themselves — they organize children. Names use kebab-case or camelCase consistently across a file; do not mix.
+
+### Token types used by grimoire-design
+
+| `$type` | Example `$value` | Used for |
+|---|---|---|
+| `color` | `"#0066ff"`, `"rgb(0,102,255)"`, `"{color.primary}"` | Backgrounds, text, borders |
+| `dimension` | `"8px"`, `"1rem"` | Spacing, sizing, border-radius |
+| `fontFamily` | `"Inter, sans-serif"`, `["Inter", "system-ui"]` | Typography stacks |
+| `fontWeight` | `400`, `"bold"` | Weight tokens |
+| `number` | `1.5`, `1.2` | Line-height ratios, opacity |
+| `duration` | `"200ms"` | Motion timing |
+| `cubicBezier` | `[0.4, 0, 0.2, 1]` | Motion easing |
+| `shadow` | `{ "color": "...", "offsetX": "...", ... }` | Elevation |
+| `asset` *(grimoire extension)* | `"./assets/logo.svg"` (path relative to repo root) | Logo and favicon paths |
+
+References use `{group.subgroup.name}` syntax: `"$value": "{color.primary}"` resolves to the token at `color.primary`.
+
+---
+
+## Required Groups (for grimoire-design consumption)
+
+A `tokens.json` that grimoire-design treats as "captured" must include at least one token in each:
+
+- `color.*` — at minimum `color.primary`. Strongly recommended: `color.secondary`, `color.accent`, `color.background`, `color.text`
+- `font.family.*` — at minimum `font.family.base`. Often also `font.family.heading`, `font.family.mono`
+- `font.size.*` — at minimum `font.size.base`. Scale tokens (`xs`, `sm`, `md`, `lg`, `xl`) are conventional
+- `spacing.*` — at minimum `spacing.base` (the unit step, e.g. `8px`). Scale tokens preferred
+
+Missing required groups → grimoire-design generates a warning and falls back to neutral defaults for that group.
+
+## Optional Groups
+
+- `motion.*` — `duration`, `easing` tokens
+- `elevation.*` or `shadow.*` — shadow stacks for cards, modals, etc.
+- `border-radius.*` — corner radii (e.g. `sm: 4px`, `md: 8px`, `pill: 9999px`)
+- `breakpoint.*` — responsive breakpoints (web surface only)
+- `asset.logo`, `asset.favicon` — see Logo / Favicon Convention below
+
+---
+
+## Complete Minimal Example
+
+```json
+{
+  "color": {
+    "primary":    { "$value": "#0066ff", "$type": "color" },
+    "secondary":  { "$value": "#6b7280", "$type": "color" },
+    "accent":     { "$value": "#f59e0b", "$type": "color" },
+    "background": { "$value": "#ffffff", "$type": "color" },
+    "text":       { "$value": "#111827", "$type": "color" }
+  },
+  "font": {
+    "family": {
+      "base":    { "$value": "Inter, sans-serif",          "$type": "fontFamily" },
+      "heading": { "$value": "Inter, sans-serif",          "$type": "fontFamily" },
+      "mono":    { "$value": "JetBrains Mono, monospace", "$type": "fontFamily" }
+    },
+    "size": {
+      "base": { "$value": "16px", "$type": "dimension" },
+      "sm":   { "$value": "14px", "$type": "dimension" },
+      "lg":   { "$value": "20px", "$type": "dimension" }
+    }
+  },
+  "spacing": {
+    "base": { "$value": "8px",  "$type": "dimension" },
+    "sm":   { "$value": "4px",  "$type": "dimension" },
+    "lg":   { "$value": "16px", "$type": "dimension" }
+  },
+  "asset": {
+    "logo":    { "$value": "./brand/logo.svg",    "$type": "asset" },
+    "favicon": { "$value": "./brand/favicon.ico", "$type": "asset" }
+  }
+}
+```
+
+---
+
+## Logo / Favicon Convention
+
+DTCG does not standardize asset references. Grimoire stores them under `asset.*` with `$type: "asset"` and a path **relative to repo root**. Tools that don't understand `$type: "asset"` ignore the node — safe to round-trip.
+
+```json
+"asset": {
+  "logo":         { "$value": "./brand/logo.svg",      "$type": "asset" },
+  "logo-dark":    { "$value": "./brand/logo-dark.svg", "$type": "asset" },
+  "favicon":      { "$value": "./brand/favicon.ico",   "$type": "asset" },
+  "favicon-svg":  { "$value": "./brand/favicon.svg",   "$type": "asset" }
+}
+```
+
+---
+
+## Voice / Tone (`voice.md`)
+
+Voice and tone are prose — DTCG does not cover them. Store as markdown alongside `tokens.json`:
+
+```markdown
+# Voice & Tone
+
+## Voice (always)
+- Direct, plain language. No marketing fluff.
+- Active voice. Short sentences.
+- Confident, not boastful.
+
+## Tone (varies by context)
+- Onboarding: warm, inviting
+- Errors: calm, blameless, with a concrete next step
+- Success: brief acknowledgement, no celebration confetti
+
+## Do
+- "Save changes" → action verb, present tense
+- "Couldn't reach the server. Retry?" → blameless, actionable
+
+## Don't
+- "Awesome! You're crushing it!" → over-celebratory
+- "An error has occurred." → vague, no recovery path
+```
+
+Sections `## Do` and `## Don't` are required; everything else is suggested structure. The Anthropic `brand-guidelines` skill convention is the source.
+
+---
+
+## Round-Trip with External Tools
+
+The format is designed to flow between tools without modification:
+
+- **Tokens Studio (Figma plugin)** — exports Figma Variables to DTCG JSON. Drop the export at `.grimoire/brand/tokens.json` and grimoire-design reads it.
+- **Style Dictionary** — compiles DTCG JSON to CSS custom properties, iOS/Android constants, JS modules. Point its source to `.grimoire/brand/tokens.json`; targets go wherever the project builds.
+- **design-extract** — scrapes a live URL and emits DTCG JSON. Pipe its output to `.grimoire/brand/tokens.json` to bootstrap from an existing site.
+
+Round-trip rule: external tools may rewrite the file; grimoire reads only `$value`, `$type`, `$description`. Unknown keys (e.g. `$extensions` from Tokens Studio) are preserved on read but not consumed.
+
+---
+
+## Validation Tips (for AI agents)
+
+When reading `tokens.json`:
+
+1. **Parse error** → emit one-line "tokens.json malformed at `<path>` — `<parse-error>`" and continue without brand grounding. Do not crash the workflow.
+2. **Missing `$value`** on a leaf node → log "skipping token `<dotted.path>` — missing `$value`". The leaf is invalid; siblings still load.
+3. **Malformed hex** (`$type: "color"` with `$value` not matching `/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/` or `rgb(...)` / `hsl(...)`) → log and skip.
+4. **Unresolved reference** (`{color.primary}` where `color.primary` does not exist) → log and treat as literal string; do not infinite-loop.
+5. **Circular reference** (A → B → A) → break at first revisit; log "circular token reference at `<path>`".
+
+When writing `tokens.json`:
+
+- Always include `$type` on every leaf. Tools that compile to typed targets need it.
+- Normalize hex to lowercase, 6-digit form. `#0066FF` → `#0066ff`. Keeps diffs clean.
+- Sort keys alphabetically within each group. Keeps round-trips with Tokens Studio stable.

package/skills/references/code-quality.md

@@ -0,0 +1,140 @@
+# Code Quality Reference
+
+Loaded by skills that write production code (`grimoire-apply`, `grimoire-bug`). Run as a checklist **after the test goes green, before marking the task done**. Same shape as the test-quality check — short, concrete, and gated.
+
+LLM-generated code drifts toward predictable failure modes: too many branches, too many guards, too many helpers wrapping single calls, too many names that mean nothing. This reference exists to make those drifts visible while the code is fresh.
+
+Most rules already live in `AGENTS.md` "Engineering Principles" and in the touched area's `.grimoire/docs/<area>.md`. Those win. This file is the concrete checklist; the principles are the source of truth.
+
+---
+
+## Quality Gate (run before marking task `[x]`)
+
+For each production file you wrote or edited, walk the seven checks below. Any failure → fix the code, re-run tests, then re-check. The gate is not a code review — it's a self-check that catches the cheap mistakes before the human reviewer sees them.
+
+### 1. Reuse before write
+
+Before adding a function, helper, type, or constant: grep for it. Check the area doc's reusable-code table if one exists. Check neighbors in the same directory.
+
+- If a function with the same job already exists → call it. Don't re-implement.
+- If something *almost* fits → use it directly first, refactor it once a second caller actually needs the change. Don't generalize on speculation.
+- If you wrote a helper used by exactly one caller → inline it. Helpers earn their name through reuse.
+
+Fail: two near-identical functions, parallel utility files, a private helper next to a public one that already does the same thing.
+
+### 2. Branching budget
+
+Count branches per function: every `if`, `else if`, `case`, `&&`/`||` in a condition, ternary, `try/except` arm, early-return guard. Aim for ≤ 7. Above that, the function does too much.
+
+Fixes (in order of preference):
+1. Delete branches that guard impossible states (see §4).
+2. Replace nested `if`/`else` ladders with early returns or a lookup table / dict.
+3. Split the function — one job per function. If the function name needs "and", split it.
+
+Fail: a 60-line function with four levels of nesting, or any function whose flow can't be described in one sentence.
+
+### 3. Function and file size
+
+- Function body > ~30 lines → look for a split. A long function is usually two functions in a trenchcoat.
+- File > ~300 lines → look for a split, unless the project's neighbors are larger.
+- One function should do one thing. If naming it forces "and" / "or" / "_helper", split first.
+
+Don't split just to hit a number. A 40-line function that reads top-to-bottom and does one thing is better than four 10-line functions that bounce around.
+
+### 4. No defensive code inside the trust boundary
+
+Validate at the edges (user input, external API responses, file/network reads). Inside, trust your callers and your types.
+
+Drop:
+- `if x is None` guards on values the type system says can't be None.
+- `try/except` that catches an exception you have no plan for and re-raises or logs-and-continues.
+- "Just in case" type checks (`isinstance`), length checks, key-exists checks on dicts you just built.
+- Fallback values for branches that can't be reached.
+
+Keep:
+- Validation of payload from a request/response/file.
+- Error handling at a real boundary with a real recovery path (retry, user message, fallback service).
+
+Fail: a private function with three guard clauses before its one real line.
+
+### 5. Names reveal intent
+
+- Locals: name the thing, not its type. `users`, not `user_list`. `unpaid_invoices`, not `data` / `result` / `temp` / `info`.
+- Booleans: read as a yes/no question. `is_expired`, `has_admin_role`, `should_retry` — not `flag`, `check`, `status`.
+- Functions: verb phrase that says what it does. `parse_invoice(raw)` not `process_data(d)`.
+- No `_v2`, `_new`, `_helper`, `_util`, `_handler` suffixes unless the project's neighbors use them.
+- Single-letter names only for indices in tight loops and well-known math conventions (`i`, `j`, `x`, `y`).
+
+Fail: any local named `data`, `result`, `temp`, `obj`, `item`, or `value` when a more specific name fits.
+
+### 6. No premature abstraction
+
+Three near-identical copies is acceptable. Extract on the fourth, or when the shared shape is stable and named. Wrong abstractions are harder to undo than duplication.
+
+Drop:
+- Generic interfaces with one implementation.
+- Config objects with one caller and one shape.
+- "Strategy" / "factory" / "registry" patterns added without a second case actually needing them.
+- Wrapper functions that only rename arguments.
+
+Keep:
+- Abstractions the codebase already uses for this kind of thing — follow the neighbor.
+- Boundaries called out in an accepted ADR.
+
+Fail: a new `BaseFoo` / `FooStrategy` / `FooFactory` introduced for a single caller.
+
+### 7. Comments earn their place
+
+Default: no comments. Add a comment **only** when the *why* is non-obvious — a hidden constraint, a workaround for a specific bug, an invariant that would surprise a future reader.
+
+Drop:
+- Comments that restate the code (`# loop over users`).
+- Comments referencing the current task / PR / ticket (`# added for issue #123`, `# used by the new flow`). These rot.
+- Multi-line docstrings on private functions whose name and signature already say everything.
+- Commented-out code. Delete it; git remembers.
+
+Keep:
+- One-line "why": the constraint, the gotcha, the link to the spec / ADR.
+- Docstrings the project's `comment_style` requires (check `.grimoire/config.yaml`).
+
+Fail: any comment whose removal would not confuse a future reader.
+
+---
+
+## Quick self-check (paste into the task loop)
+
+Before marking a task `[x]`:
+
+- [ ] Searched for existing utilities before writing new ones (§1)
+- [ ] No function with more than ~7 branches or ~30 lines without a reason (§2, §3)
+- [ ] No guards / try-except / type-checks inside the trust boundary (§4)
+- [ ] No locals named `data`, `result`, `temp`, `info`, `obj` — names reveal intent (§5)
+- [ ] No new abstractions, interfaces, or wrappers with a single caller (§6)
+- [ ] No comments describing *what* the code does — only *why*, and only when non-obvious (§7)
+- [ ] Diff stays inside the task's scope — no "while I'm here" refactors
+
+If any box can't be ticked, fix the code (not the checklist) and re-run tests.
+
+---
+
+## Anti-patterns by symptom
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Function is 80 lines with 5 levels of nesting | Too many jobs, defensive guards | Split + drop dead guards (§2, §3, §4) |
+| Three helper files for one feature | Premature abstraction | Inline back, extract once a real second caller exists (§6) |
+| `data`, `result`, `obj` everywhere | Generic names from training data | Rename to the actual concept (§5) |
+| Every function starts with `if x is None: return` | Defensive habit | Trust the caller; validate once at the edge (§4) |
+| Comments restate variable names | Filler | Delete (§7) |
+| `try: ... except Exception: pass` | Hiding bugs | Remove or handle the specific exception with a real recovery (§4) |
+| Wrapper `def get_user(id): return db.get_user(id)` | Pointless indirection | Inline (§1) |
+| Two near-identical functions differing by one constant | Copy-paste instead of reuse | Pass the constant as a parameter, or call the existing one (§1) |
+
+---
+
+## Notes for the reviewer / self
+
+- The gate is **per file, per task**. Not a separate review pass.
+- "I'll clean it up later" is the failure mode. Clean it before the test goes green stays green.
+- If a check seems wrong for *this* codebase, the project's `AGENTS.md` / area doc / neighbor patterns win. Cite the override; don't ignore silently.
+- The full review-stage Senior Engineer + Code Style personas (`./review-personas.md`) catch what slipped through. This gate exists so they have less to catch.