fix(site/VerdictExplanation): findings list now reads as cards, not a wall

On a malicious skill the Reasons section was 8 category headings and
14 rule blocks stacked vertically, every header rendered in the same
text-sm font-medium with a hairline divider, every rule body the
same color. With nothing to grab onto visually the eye slid past it.

Restructured the findings as a grid of category cards:

- Each category is a card with a colored left strip whose tone is
  the maximum severity present in the category (red for high or
  critical, amber for medium, neutral for low or info). The previous
  uniform border told you nothing; now you can spot the worst
  categories at a glance.
- Category header carries a SeverityBadges row on the right showing
  the count per severity present in that category, for example
  '5 high  2 medium'. Lets you prioritize without expanding each
  rule.
- Every rule gets a filled severity dot, a bold mono ID, the
  severity word in the severity tone, and the hit count. Same data
  the rule_severity field carried all along, just rendered.
- Rules within a category sort by severity-desc then count-desc so
  the worst rule of each cluster is at the top. Categories sort by
  max severity, then by total count.
- On md+ widths the cards flow into two CSS columns with
  break-inside-avoid, cutting the section to roughly half its
  previous height without losing any text. On narrow viewports the
  layout collapses to one column.
- When there are four or more categories, a JumpBar of compact
  pills appears above the cards. Each pill is the category name,
  the max-severity dot, and the total count, and links to the
  category's anchor id. Anchors are stable slugs so deep links
  work even after re-scans.

Rule item layout is now two rows: a header row with
'• PE3  HIGH  · 5 hits' (severity is colored), and a body row with
the description as its own paragraph. The previous single-line
'PE3 · 5 hits Code accesses credential files...' smashed the
machine-readable bits up against the prose.

Tested with the live DOM dumped through an HTML parser to verify
the copy-paste output is clean, plus pnpm lint, lint-types,
test:ci, and build. Existing Storybook fixtures already carry the
severity field so the stories did not need updating.

Author: DevelopmentCats

site/src/components/VerdictExplanation/VerdictExplanation.tsx

@@ -16,10 +16,76 @@ interface VerdictExplanationProps {
   className?: string;
 }
 
+const SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"] as const;
+type SeverityKey = (typeof SEVERITY_ORDER)[number];
+
+interface RuleItem {
+  id: string;
+  severity: SeverityKey;
+  count: number;
+  description: string;
+}
+
 interface CategoryGroup {
   category: string;
+  /** Total `count` across rules in the category. */
   totalCount: number;
-  rules: { id: string; severity: string; count: number; description: string }[];
+  /** Highest severity present; drives the card's accent color. */
+  maxSeverity: SeverityKey;
+  /** Tally per severity, used for the right-side summary on the card. */
+  bySeverity: Record<SeverityKey, number>;
+  rules: RuleItem[];
+}
+
+const SEVERITY_TONE: Record<
+  SeverityKey,
+  {
+    /** Used for the colored left-side accent strip on the card. */
+    accent: string;
+    /** Severity word color in the rule header. */
+    text: string;
+    /** Filled dot before the rule ID. */
+    dot: string;
+  }
+> = {
+  critical: {
+    accent: "bg-verdict-malicious",
+    text: "text-verdict-malicious",
+    dot: "bg-verdict-malicious",
+  },
+  high: {
+    accent: "bg-verdict-malicious",
+    text: "text-verdict-malicious",
+    dot: "bg-verdict-malicious",
+  },
+  medium: {
+    accent: "bg-verdict-suspicious",
+    text: "text-verdict-suspicious",
+    dot: "bg-verdict-suspicious",
+  },
+  low: {
+    accent: "bg-coder-neutral-500",
+    text: "text-coder-neutral-300",
+    dot: "bg-coder-neutral-500",
+  },
+  info: {
+    accent: "bg-coder-neutral-600",
+    text: "text-coder-neutral-400",
+    dot: "bg-coder-neutral-600",
+  },
+};
+
+function severityKey(sev?: string): SeverityKey {
+  const s = (sev ?? "info").toLowerCase();
+  return (SEVERITY_ORDER as readonly string[]).includes(s)
+    ? (s as SeverityKey)
+    : "info";
+}
+
+function severityRank(s: SeverityKey): number {
+  // Lower index = more severe. Mirror SEVERITY_ORDER so sort key is
+  // monotonically ascending for severity-desc ordering.
+  return SEVERITY_ORDER.indexOf(s);
 }
 
 function groupByCategory(findings: FindingByRule[]): CategoryGroup[] {
@@ -29,23 +95,46 @@ function groupByCategory(findings: FindingByRule[]): CategoryGroup[] {
     const category = rule?.category || "Other";
     let slot = map.get(category);
     if (!slot) {
-      slot = { category, totalCount: 0, rules: [] };
+      slot = {
+        category,
+        totalCount: 0,
+        maxSeverity: "info",
+        bySeverity: { critical: 0, high: 0, medium: 0, low: 0, info: 0 },
+        rules: [],
+      };
       map.set(category, slot);
     }
+    const sev = severityKey(f.severity);
     slot.totalCount += f.count;
+    slot.bySeverity[sev] += f.count;
+    if (severityRank(sev) < severityRank(slot.maxSeverity)) {
+      slot.maxSeverity = sev;
+    }
     slot.rules.push({
       id: f.id,
-      severity: f.severity,
+      severity: sev,
       count: f.count,
       description: rule?.description ?? "",
     });
   }
-  return Array.from(map.values())
-    .map((group) => ({
-      ...group,
-      rules: group.rules.sort((a, b) => b.count - a.count),
-    }))
-    .sort((a, b) => b.totalCount - a.totalCount);
+  for (const group of map.values()) {
+    // Within a category, lead with the most severe rules; break ties by
+    // hit count so a louder rule edges out a quieter one at the same
+    // severity. Falls back to alphabetical ID for full determinism.
+    group.rules.sort((a, b) => {
+      const sev = severityRank(a.severity) - severityRank(b.severity);
+      if (sev !== 0) return sev;
+      if (a.count !== b.count) return b.count - a.count;
+      return a.id.localeCompare(b.id);
+    });
+  }
+  return Array.from(map.values()).sort((a, b) => {
+    // Categories ordered by max severity, then by total count desc so
+    // the worst clusters lead.
+    const sev = severityRank(a.maxSeverity) - severityRank(b.maxSeverity);
+    if (sev !== 0) return sev;
+    return b.totalCount - a.totalCount;
+  });
 }
 
 const VERDICT_TONE: Record<
@@ -54,10 +143,6 @@ const VERDICT_TONE: Record<
     icon: typeof ShieldAlertIcon;
     chipClass: string;
     label: string;
-    /** One-sentence narrative, no data restated. The Risk score panel
-     *  directly above the Reasons section already shows the score,
-     *  severity, and recommendation; this chip should interpret, not
-     *  restate. */
     summary: string;
   }
 > = {
@@ -107,6 +192,133 @@ function thresholdSentence(
   return null;
 }
 
+function slugifyCategory(name: string): string {
+  return `cat-${name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "")}`;
+}
+
+interface SeverityBadgesProps {
+  counts: Record<SeverityKey, number>;
+}
+
+const SeverityBadges: FC<SeverityBadgesProps> = ({ counts }) => {
+  const present = SEVERITY_ORDER.filter((s) => counts[s] > 0);
+  if (present.length === 0) return null;
+  return (
+    <div className="flex flex-wrap items-center gap-x-2 gap-y-1 font-mono text-[10px] uppercase tracking-wider">
+      {present.map((sev) => (
+        <span
+          key={sev}
+          className={cn("inline-flex items-center gap-1", SEVERITY_TONE[sev].text)}
+        >
+          <span
+            aria-hidden
+            className={cn("size-1.5 rounded-full", SEVERITY_TONE[sev].dot)}
+          />
+          {counts[sev]} {sev}
+        </span>
+      ))}
+    </div>
+  );
+};
+
+interface JumpBarProps {
+  categories: CategoryGroup[];
+}
+
+const JumpBar: FC<JumpBarProps> = ({ categories }) => (
+  <nav
+    aria-label="Findings by category"
+    className="-mx-1 mb-3 flex flex-wrap gap-1 text-xs"
+  >
+    {categories.map((cat) => (
+      <a
+        key={cat.category}
+        href={`#${slugifyCategory(cat.category)}`}
+        className="inline-flex items-center gap-1.5 rounded-full border border-coder-smoke bg-coder-cinder px-2.5 py-1 text-coder-neutral-300 transition-colors hover:border-coder-smoke-lighter hover:bg-coder-smoke/40 hover:text-coder-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-coder-sky focus-visible:ring-offset-1 focus-visible:ring-offset-coder-cinder"
+      >
+        <span
+          aria-hidden
+          className={cn(
+            "size-1.5 rounded-full",
+            SEVERITY_TONE[cat.maxSeverity].dot,
+          )}
+        />
+        <span>{cat.category}</span>
+        <span className="font-mono text-coder-neutral-500">
+          {cat.totalCount}
+        </span>
+      </a>
+    ))}
+  </nav>
+);
+
+interface CategoryCardProps {
+  group: CategoryGroup;
+}
+
+const CategoryCard: FC<CategoryCardProps> = ({ group }) => {
+  const accent = SEVERITY_TONE[group.maxSeverity];
+  return (
+    <article
+      id={slugifyCategory(group.category)}
+      className="mb-3 break-inside-avoid overflow-hidden rounded-md border border-coder-smoke bg-coder-cinder/60"
+    >
+      <header className="flex items-stretch">
+        <span
+          aria-hidden
+          className={cn("w-1 shrink-0", accent.accent)}
+        />
+        <div className="flex flex-1 flex-wrap items-baseline justify-between gap-x-4 gap-y-1 px-3 py-2.5">
+          <h4 className="text-sm font-semibold text-coder-neutral-100">
+            {group.category}
+          </h4>
+          <SeverityBadges counts={group.bySeverity} />
+        </div>
+      </header>
+      <ul className="divide-y divide-coder-smoke/40">
+        {group.rules.map((rule) => {
+          const tone = SEVERITY_TONE[rule.severity];
+          return (
+            <li key={rule.id} className="space-y-1 px-3 py-2.5">
+              <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1 text-xs">
+                <span
+                  aria-hidden
+                  className={cn(
+                    "mb-px size-1.5 rounded-full self-center",
+                    tone.dot,
+                  )}
+                />
+                <span className="font-mono font-medium text-coder-neutral-100">
+                  {rule.id}
+                </span>
+                <span
+                  className={cn(
+                    "font-mono uppercase tracking-wide",
+                    tone.text,
+                  )}
+                >
+                  {rule.severity}
+                </span>
+                <span className="font-mono text-coder-neutral-500">
+                  {"\u00b7"} {rule.count}{" "}
+                  {rule.count === 1 ? "hit" : "hits"}
+                </span>
+              </div>
+              <p className="text-xs leading-relaxed text-coder-neutral-300">
+                {rule.description || (
+                  <span className="text-coder-neutral-500">
+                    (no description in the bundled rule catalogue)
+                  </span>
+                )}
+              </p>
+            </li>
+          );
+        })}
+      </ul>
+    </article>
+  );
+};
+
 export const VerdictExplanation: FC<VerdictExplanationProps> = ({
   skill,
   // Defaults match config.yaml and scanner/verdict.py. They are also
@@ -178,42 +390,21 @@ export const VerdictExplanation: FC<VerdictExplanationProps> = ({
               {categories.length === 1 ? "category" : "categories"}
             </span>
           </div>
-          <ul className="space-y-4">
+
+          {/* Show the jump bar once the list runs long enough that a
+              user might want to navigate to a specific area instead of
+              scrolling top-to-bottom. */}
+          {categories.length >= 4 && <JumpBar categories={categories} />}
+
+          {/* CSS multi-column layout: at md+ widths the cards flow into
+              two columns and `break-inside-avoid` keeps each category
+              card together. This collapses the previous tall list to
+              roughly half its height without losing any information. */}
+          <div className="md:columns-2 md:gap-4">
             {categories.map((cat) => (
-              <li key={cat.category}>
-                <div className="flex items-baseline justify-between gap-3 border-b border-coder-smoke/60 pb-1">
-                  <h4 className="text-sm font-medium text-coder-neutral-100">
-                    {cat.category}
-                  </h4>
-                  <span className="font-mono text-xs tabular-nums text-coder-neutral-500">
-                    {cat.totalCount}
-                  </span>
-                </div>
-                <ul className="mt-2 space-y-2.5">
-                  {cat.rules.map((rule) => (
-                    <li key={rule.id} className="space-y-0.5">
-                      <div className="flex items-baseline gap-2 text-xs">
-                        <span className="font-mono font-medium text-coder-neutral-100">
-                          {rule.id}
-                        </span>
-                        <span className="font-mono text-coder-neutral-500">
-                          {"\u00b7"} {rule.count}{" "}
-                          {rule.count === 1 ? "hit" : "hits"}
-                        </span>
-                      </div>
-                      <p className="text-xs leading-relaxed text-coder-neutral-300">
-                        {rule.description || (
-                          <span className="text-coder-neutral-500">
-                            (no description in the bundled rule catalogue)
-                          </span>
-                        )}
-                      </p>
-                    </li>
-                  ))}
-                </ul>
-              </li>
+              <CategoryCard key={cat.category} group={cat} />
             ))}
-          </ul>
+          </div>
         </div>
       )}