@kiwidata/grimoire 0.1.3 → 0.1.5

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,172 @@
+# 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: query the graph (`search_graph` by concept and by name) for an existing one. Then grep, and 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 — terse, self-contained, no essays
+
+Write comments like a senior engineer with no time: dense, professional, zero filler.
+
+**Voice: terse.** "Resolve model by id; raises on unknown provider." — not "This function is responsible for resolving the model by its id, and it will raise an exception if the provider is not known." Drop "this function", "we", hedging, and restated types. Fragments are fine; full prose grammar is not required.
+
+**Self-contained.** A comment describes the function/class on its own terms only. It must NOT name an external artifact that changes independently — feature flags / `.feature` files / scenario names, unit or integration test names, MADR/ADR numbers, change-ids, issue/PR numbers, tag codes (`LOG-OBS-003`). Those orphan the moment the artifact moves, and rot silently. Describe the *behavior*, not where it's specced.
+- OK: `# skip third-party sinks (e.g. behave capture)` — generic, about the code.
+- Not OK: `# implements scenario LOG-OBS-003 from logging.feature` — points at an artifact that will move.
+
+**No paragraphs.** Summary is one line, two at most. No prose block explaining the whole design before the params. If the rationale needs a paragraph, it belongs in a decision record — not the code.
+
+**Params per `comment_style` are fine.** If the project's style (sphinx/google/jsdoc/…) calls for `:param`/`Args:`/`@param`, keep them — but describe a param only when its name + type don't already say it, and don't precede them with prose.
+
+Drop:
+- Comments that restate the code (`# loop over users`).
+- Any reference to a task / PR / ticket / feature / scenario / ADR / specific test (`# added for issue #123`, `# covers scenario X`, `# see test_foo`). Self-contained or gone.
+- Multi-line prose docstrings on private functions whose name + signature already say everything.
+- Commented-out code. Delete it; git remembers.
+
+Keep:
+- One terse line of *why* when non-obvious — a hidden constraint, a workaround, a surprising invariant — stated in terms of the code itself.
+- The structured `comment_style` param/return section, terse.
+
+Fail: any comment that (a) wouldn't confuse a future reader if removed, (b) names an external artifact, or (c) runs to a prose paragraph.
+
+**Before / after** (the offender this rule targets):
+```python
+# BEFORE — orphan-prone essay
+def build_chat(model_id):
+    """
+    Build and return a chat model for the given model id. This is the primary
+    entry point used by every agent and team in the system, as specified by
+    scenario LOG-OBS-003 in logging.feature and decided in ADR-0001. See
+    test_build_chat for the expected behavior. Added as part of add-2fa-login.
+
+    :param model_id: the id of the model to build
+    :return: the chat model
+    """
+
+# AFTER — terse, self-contained
+def build_chat(model_id):
+    """Resolve a chat model by id. Raises on an unknown provider.
+
+    :param model_id: provider-prefixed model id (e.g. "gpt-4.1-mini")
+    """
+```
+
+---
+
+## 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)
+- [ ] Comments are terse, self-contained, ≤2 lines of prose — no *what*, no external-artifact refs (feature/scenario/ADR/test/ticket) (§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.

package/skills/references/container-scan-triage.md

@@ -0,0 +1,102 @@
+# Container & OS-Package Scan Triage Reference
+
+The deep-dive for `os-package` / `container` / `iac` findings from image scanners (Trivy, Grype). Loaded by `grimoire-vuln-triage` when a scan carries container/OS-package results. The general rubric — normalize, reconcile, KEV/EPSS, VEX, urgency, Contrarian — lives in `./dependency-vuln-triage.md`; this file is the discipline for the part that goes wrong most: deciding what to *do* about a base-OS CVE.
+
+Written after a review recommended removing `Mesa`, `ncurses`, and `krb5` from a headless Django API with the rationale "no business in a headless API." Two of the three could not be removed without breaking the image. This guide exists so that mistake is not repeated.
+
+## Separate the two axes — they are not the same question
+
+- **Reachability** — *is the vulnerable code path actually called by untrusted input in this service?* Decides **urgency** (hotfix / next-release / accept). A library present but never invoked is low risk even at CVSS CRITICAL.
+- **Removability** — *can we delete the package, and what breaks if we do?* Decides **remediation** (Dockerfile edit / base bump / accept+document).
+
+Conflating them produces the classic error: "this lib is unreachable, so remove it." Unreachable ≠ removable. A headless API genuinely cannot reach Mesa's OpenGL code — **and also cannot remove Mesa** if it arrived transitively behind a package it needs. Judge both, separately.
+
+## Core rule: trace before you recommend
+
+A CVE scanner reports *what is present*, not *why* or *whether it is removable*. Never recommend removing a package until you have answered all three:
+
+1. **How does it get in?** Directly installed, transitive, base image, or builder-stage-only?
+2. **What depends on it?** Application code, a required runtime lib, or the base OS?
+3. **What breaks if it's gone?** Build, runtime, or nothing — and what's the test that proves it?
+
+"This doesn't belong in a headless API" is an assumption, not an analysis.
+
+## Step A — How is it installed?
+
+Search the Dockerfile for an explicit install line first.
+
+- **Explicitly installed** (named in `apt-get install` / `pip install`): a real removal candidate — continue to Step B.
+- **Not named anywhere**: it's transitive — pulled by another package or shipped in the base image. You cannot `apt-get remove` it without breaking its parent. Identify the parent before saying anything.
+
+Common transitive sources — map these before flagging:
+
+| Flagged lib | Usually pulled in by | Notes |
+|---|---|---|
+| krb5 / libgssapi-krb5 | `libpq5`, `postgresql-client`, `curl` | Postgres GSSAPI/Kerberos auth |
+| ncurses / libtinfo | base image | bash, apt, dpkg, python readline link it |
+| Mesa / libgl1 / libgbm | `libgl1`, `libglib2.0-0` | OpenCV / docling / easyocr deps |
+| OpenSSL / libssl | base image + most TLS clients | almost never removable |
+| libexpat1 | base image + python (`pyexpat`) | stdlib XML |
+
+## Step B — What actually depends on it?
+
+Do not assume. Check the repo:
+
+- **App imports** — grep for the consuming module (`import cv2`, `import magic`, `import pyodbc`, `gssapi`, `lxml`).
+- **System tools used at runtime** — grep code, scripts, and the entrypoint for the binary (`psql`, `pg_dump`, `pg_isready`).
+- **Driver bundling** — many Python wheels bundle their native lib, making the system package redundant. `psycopg-binary` bundles libpq → system `libpq5` not needed for the driver; `pylibmagic` bundles libmagic → system `libmagic1` may be redundant. When a binary wheel is present, the matching system runtime package is often dead weight — **verify, then say so**.
+- **Cross-service config trap** — env vars or paths in this repo may configure a *different* container. `EASYOCR_MODULE_PATH` / `DOCLING_ARTIFACTS_PATH` in bake are passed by `job_runner.py` to the **ricky** pipeline container — they do **not** mean bake runs easyocr/docling. Never justify or condemn a package using a string that belongs to another service.
+
+## Step C — Know what is not removable
+
+Some findings are not actionable by editing an install line:
+
+- **Base-image packages** (ncurses, OpenSSL, glibc, zlib, expat): part of the OS. Removing breaks bash/apt/dpkg or the Python runtime. The only real mitigations are: **switch to a smaller/distroless base**, **bump the base image** for patched versions, or **accept and document** the risk. State which — do not tell the user to "remove" it.
+- **Transitive deps of required libs** (e.g. krb5 behind `libpq5`): removable only by also removing the parent, and only if the parent is itself unneeded.
+
+## Step D — Multi-stage builds: target the right stage
+
+In a multi-stage Dockerfile only the final stage ships. Packages in a `builder` stage (compilers, `-dev` headers) do **not** appear in the runtime image if only the artifact (`/opt/venv` or equivalent) is copied forward. They are not runtime attack surface. Don't flag builder-stage packages as runtime risk; if you mention them, label them **build-only**.
+
+## Step E — Assess real risk, not just presence (reachability)
+
+Maps to `./dependency-vuln-triage.md` § Reachability. A CVE in a library never reached by untrusted input is lower priority than its score. For each finding note:
+
+- Is the vulnerable code path reachable in *this* service? (use the consumer map below — grep the **consumer**, not the C package name; the app never `import`s `libexpat1`)
+- Network/user-input exposed, or internal-only?
+- Headless API context: no display, no user shell, no interactive TTY → GUI/terminal libs (Mesa, ncurses) are usually unreachable even when present.
+
+| OS package | Reached only if the app… | Grep for |
+|---|---|---|
+| libexpat1 | parses XML via stdlib | `xml.etree`, `xml.sax`, `pyexpat`, `minidom` |
+| libxml2 / libxslt | parses XML/XSLT via lxml | `import lxml`, `etree`, `XSLT` |
+| krb5 / libgssapi | does Kerberos/GSSAPI auth | `gssapi`, `kerberos`, `requests_kerberos` |
+| mesa / libGL / libgbm | does GPU/OpenGL rendering | `OpenGL`, `moderngl`, `cv2` (headless API: none) |
+| ncurses / libtinfo | drives an interactive terminal | `curses`, `pty`, `readline` (web process: none) |
+| libssl / openssl | does TLS | usually reachable — judge on impact |
+| imagemagick / libvips | processes user-uploaded images | the upload/convert path |
+
+**Grep can lie — verify the binding.** `Price.fromstring()` (price-parser) is not `etree.fromstring()` (XML). Confirm the match is the real vulnerable call site before asserting `not_affected` or `affected`; if you can't, mark `under_investigation` and name what a human must check. Prefer reachability-based prioritization over raw CVSS.
+
+## Honor the scanner's fix-state
+
+Trivy `Status` (and Grype `fix.state`): `fixed` → a patched package exists; upgrade/rebuild is the lever. `affected` / `will_not_fix` / `end_of_life` → **no fix available**; the lever is *accept with expiry* or *rebuild on a newer/slimmer base when one ships* — **not** an "upgrade X" ticket. `under_investigation` → distro hasn't ruled; mirror it. Never file an upgrade task for a no-fixed-version finding.
+
+## Output per flagged package
+
+1. **Package + CVE(s)** — what the scanner said (and the dedup count if one CVE spans many packages).
+2. **How it's installed** — explicit line N / transitive via `<parent>` / base image / builder-only.
+3. **What depends on it** — app module / runtime tool / OS, with grep evidence.
+4. **Reachable?** — vulnerable path called by untrusted input? (provenance: graph / grep / image-layer / unknown)
+5. **Removable?** — Yes (safe) / Yes (after removing `<parent>`, test X) / No (base OS) / No (required by Y).
+6. **Recommendation** — exact Dockerfile edit, or "patch/bump base image", or "accept + document", **plus the post-change test** (build, import, DB connect). Route image-structure changes to infra / `grimoire-draft`, not app remediation.
+
+## Anti-patterns — do not do these
+
+- ❌ "X has no business in a headless API" with no trace of how X got installed.
+- ❌ Recommending `apt-get remove` of a base-image or transitive package.
+- ❌ Treating scanner presence as equal to exploitable risk.
+- ❌ Justifying or condemning a package using config that targets another service.
+- ❌ Flagging builder-stage packages as runtime attack surface.
+- ❌ Recommending removal without naming the post-change test.
+- ❌ Filing an "upgrade" ticket for a `will_not_fix` / no-fixed-version finding.