@hegemonart/get-design-done 1.22.0 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.22.0"
+    "version": "1.23.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.22.0",
+      "version": "1.23.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.23.0] — 2026-04-25
+
+Phase 23 GDD SDK Domain Primitives milestone — lands the highest-leverage code primitives from the ROADMAP "GDD SDK Domain Primitives" entry as typed Node modules with tests. 10 atomic plans (23-01 through 23-10), additive — every Phase 20/21/22 consumer keeps working unchanged. Distribution as separate `@hegemonart/gdd-sdk` npm package and screenshot-capture orchestration are explicitly deferred to follow-up phases.
+
+### Added
+
+- **JSON output contracts** — `reference/output-contracts/planner-decision.schema.json` + `verifier-decision.schema.json` (Draft-07). `scripts/lib/parse-contract.cjs` gains `parsePlannerDecision()` and `parseVerifierDecision()` riding the same extract→parse→validate pipeline as the existing `parseMotionMap`. Lets `/gdd:synthesize` consume planner output without regex-parsing markdown headings, and lets executor↔verifier ping-pong on a typed envelope. (Plan 23-01)
+
+- **Solidify-with-rollback gate** — `scripts/lib/design-solidify.mjs` runs the typecheck/build/targeted-test triplet for a task and, on any failure, rolls the working tree back via `git stash` (configurable: `stash` | `hard` | `none`) and emits a `solidify.rollback` event onto the Phase 22 causal chain. Optional `emit()` callback for event-stream telemetry sink. Authored as `.mjs` to sidestep the Phase 22 Node 24 + Windows + .mjs↔.ts loader bug. (Plan 23-02)
+
+- **Touches: analyzer + parallelism decision engine** — `scripts/lib/touches-analyzer/index.cjs` parses `Touches:` lines from task markdown into glob lists and produces a pairwise verdict (`parallel` | `sequential`) for any two tasks. Encodes today's prompt-only heuristic into auditable code. Verdict rules (first match wins): empty → unknown-touches; literal equality → shared-glob; shared component dir → shared-component-dir; resolved-file overlap → shared-file; otherwise → disjoint. (Plan 23-03)
+
+- **Audit aggregator** — `scripts/lib/audit-aggregator/index.cjs` takes `Array<Finding>` from N audit-agents, dedups by `{file, line, rule_id}`, scores via severity-weighted formula (P0:8/P1:4/P2:2/P3:1), and returns sorted top-N + tally summary. Default merge picks higher-confidence → higher-severity → lex-earliest agent → first-seen. Confidence outside `[0, 1]` clamped with one `process.emitWarning` per call. Cross-platform path normalization. (Plan 23-04)
+
+- **Reference resolver** — `scripts/lib/reference-resolver.cjs` adds the resolution direction on top of the Phase 14.5 reference-registry. `resolve('forms')` / `resolve('type:forms')` → `{name, path, type, excerpt}` with a 200-char excerpt suitable for inlining into agent prompts. Lookup order: exact name → slug match → singularize fuzzy → type-only-when-unique. Ambiguous match throws `RangeError` with candidates. `resolveAll(keys, {ignoreMissing})` for bulk. `excerptOf(path, {maxChars})` strips frontmatter / fenced code / HTML comments / markdown headers. (Plan 23-05)
+
+- **Touches pattern miner** — `scripts/lib/touches-pattern-miner.cjs` scans `.design/archive/cycle-*/tasks/*.md` after `/gdd:complete-cycle`, canonicalizes signatures (lowercase + backslash-normalize + cycle-slug strip + dedup + sort), and proposes crystallization candidates when a signature recurs in ≥3 tasks across ≥2 cycles. Writes `.design/learnings/touches-patterns.json` atomically (`.tmp` + rename). **NEVER auto-applies** — `/gdd:apply-reflections` is the materialization gate. (Plan 23-06)
+
+- **Image diff + visual baseline manager** — `scripts/lib/visual-baseline/diff.cjs` compares two PNG buffers. With `pngjs` installed (probeOptional), decodes both and counts pixels whose R/G/B/A channels differ beyond the tolerance (default 4). Without `pngjs`, falls back to bytewise SHA-256 equality. `scripts/lib/visual-baseline/index.cjs` exposes `compareToBaseline(key, pngBuffer)` and `applyBaseline(key, pngBuffer)`; reads/writes `.design/baselines/<key>.png`; rejects path-traversal keys. `pngjs@7` declared as optional dep. Defers Playwright/Preview MCP screenshot capture orchestration to a later phase. (Plan 23-07)
+
+- **Design-token reader (multi-source)** — `scripts/lib/design-tokens/index.cjs` facades over four pure-JS readers producing the uniform `{tokens, source, format, warnings}` shape:
+  - `css-vars.cjs` — extracts `--token: value;` from CSS/SCSS, last-write-wins, strips block comments, warns on `$scss-vars`
+  - `js-const.cjs` — spawn-node harness evaluates CJS/ESM exports, recognises `{tokens: …}` / default / direct bag, flattens nested with `.` separator
+  - `tailwind.cjs` — same harness, walks `theme` + `theme.extend` per scale (extend overrides base)
+  - `figma.cjs` — parses `{variableCollections}` shape OR already-flattened bag; emits `rgb(R, G, B)` for color values, per-mode tokens for multi-mode variables
+  Auto-detection by extension + content sniff. (Plan 23-08)
+
+- **Domain primitives bundle** — three checkers sharing a single hit shape (`{rule_id, severity P0-P3, summary, evidence?, line?, file}`):
+  - `domain-primitives/nng.cjs` — runs grep-style heuristic rules loaded from `reference/heuristics.md` fenced yaml blocks; caller may inject `opts.rules` to bypass file-load
+  - `domain-primitives/anti-patterns.cjs` — same yaml extractor against `reference/anti-patterns.md`
+  - `domain-primitives/wcag.cjs` (no axe-core dep) — `contrastRatio()` (WCAG 1.4.3 luminance), `checkContrast({fg, bg, level: AA|AAA})`, `checkTapTarget({width, height, level})` (AA 24×24, AAA 44×44), `checkAriaLabels({content})` (interactive elements without text + aria-label)
+  Both NNG + anti-pattern files allow no parseable yaml today (treated as empty registry); robust to gradual rule population. (Plan 23-09)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.23.0`.
+- `test-fixture/baselines/phase-20/resilience-primitives.txt` gains `reference-resolver.cjs` (alphabetical between `reference-registry.cjs` and `relevance-counter.cjs`) and `touches-pattern-miner.cjs` (alphabetical at end).
+
+### Tests
+
+- `tests/output-contracts-23-01.test.cjs` — planner + verifier contracts (14 tests)
+- `tests/design-solidify.test.cjs` — solidify gate, all rollback modes (6)
+- `tests/touches-analyzer.test.cjs` — parser + verdict + matrix (17)
+- `tests/audit-aggregator.test.cjs` — dedup + score + tallies (15)
+- `tests/reference-resolver.test.cjs` — resolution rules + excerpts (12)
+- `tests/touches-pattern-miner.test.cjs` — canonicalize + thresholds + atomic write (10)
+- `tests/visual-baseline.test.cjs` — diff modes + baseline round-trip (14, pngjs-optional path skipped when absent)
+- `tests/design-tokens.test.cjs` — 4 readers + facade auto-detect (15)
+- `tests/domain-primitives.test.cjs` — NNG + anti-pattern + WCAG checkers (18)
+- `tests/phase-23-baseline.test.cjs` — Phase 23 regression baseline (12)
+
+Total: 133 new tests. All Phase 20/21/22 tests still green.
+
+### Deferred
+
+- **`@hegemonart/gdd-sdk` separate npm package** — out of scope; build/packaging project of its own.
+- **Screenshot capture orchestration** (Playwright + Claude Preview MCP wrapper) — needs live MCP infra to validate.
+- **Spec↔code↔visual triangulation verifier** — depends on Phase 16/17 component specs being fleshed out.
+- **Knowledge-graph typed query layer** + cycle/workstream model SDK + pause/resume context serializer SDK + per-stage budget allocator SDK + git operations primitive + handoff bundle parser + intel store typed reader/writer — each is roadmap-text-sized and warrants its own phase scope.
+
+---
+
 ## [1.22.0] — 2026-04-25
 
 Phase 22 GDD SDK Observability milestone — the single-typed `BaseEvent` envelope from Phase 20 grows into a queryable, redacted, transport-able observability layer with tail/grep/WebSocket consumers and a causal event chain. 10 plans (22-01 through 22-10), additive — every Phase 20 + Phase 21 consumer keeps working unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -87,6 +87,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "optionalDependencies": {
+    "pngjs": "^7.0.0",
     "ws": "^8.20.0"
   }
 }

package/reference/output-contracts/planner-decision.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "planner-decision.schema.json",
+  "title": "Planner Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-planner. Lets /gdd:synthesize and downstream consumers (executor, audit aggregator) read planner output without regex-parsing markdown.",
+  "type": "object",
+  "required": ["schema_version", "plan_id", "tasks", "waves"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "plan_id": {
+      "type": "string",
+      "description": "Stable identifier — e.g. '23-04' or 'PLAN.md'.",
+      "minLength": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["task_id", "summary", "touches"],
+        "additionalProperties": false,
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable per-plan task identifier (e.g. T-01, 23-04-T-1)."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 3
+          },
+          "touches": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "File globs the task is expected to read or write."
+          },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Other task_ids that must complete first.",
+            "default": []
+          },
+          "parallel_safe": {
+            "type": "boolean",
+            "description": "Hint from the planner — the parallelism decision engine confirms via Touches: analysis.",
+            "default": false
+          },
+          "estimated_minutes": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Rough wall-clock estimate; consumed by budget allocator."
+          },
+          "acceptance": {
+            "type": "string",
+            "description": "Free-form acceptance criteria copy."
+          }
+        }
+      }
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["wave", "task_ids"],
+        "additionalProperties": false,
+        "properties": {
+          "wave": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Wave label (e.g. 'A', 'B', 'C')."
+          },
+          "task_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form planner-side rationale — not consumed by code."
+    }
+  }
+}

package/reference/output-contracts/verifier-decision.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "verifier-decision.schema.json",
+  "title": "Verifier Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-verifier. Drives executor↔verifier ping-pong with a typed envelope rather than free-form prose.",
+  "type": "object",
+  "required": ["schema_version", "verdict", "gaps", "must_fix_before_ship", "confidence"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["pass", "fail", "gap"],
+      "description": "pass = ship-ready, gap = remediable, fail = re-plan."
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "area", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"]
+          },
+          "area": {
+            "type": "string",
+            "description": "Free-form domain tag — e.g. 'a11y', 'motion', 'tokens'."
+          },
+          "summary": { "type": "string", "minLength": 3 },
+          "evidence": {
+            "type": "string",
+            "description": "Citation: file:line reference or audit excerpt."
+          },
+          "remediation": {
+            "type": "string",
+            "description": "One-line proposed fix."
+          }
+        }
+      }
+    },
+    "must_fix_before_ship": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Subset of gap.id values that block ship — typically the P0/P1 ones."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "med", "low"],
+      "description": "Verifier's self-rated confidence — drives whether to escalate to a second pass."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form notes — not code-consumed."
+    }
+  }
+}

package/scripts/lib/audit-aggregator/index.cjs

@@ -0,0 +1,219 @@
+/**
+ * audit-aggregator/index.cjs — dedup + score + rank findings from N
+ * audit-agents (Plan 23-04).
+ *
+ * Replaces the prompt-only "trust the agent's score" pattern with a
+ * deterministic scoring + dedup function that downstream tooling
+ * (`/gdd:audit`, `/gdd:reflect`) can rely on.
+ *
+ * Dedup key: `${lowercased(normalizePath(file))}::${line ?? 0}::${rule_id}`.
+ * Survivor selection on collision:
+ *   1. higher confidence wins
+ *   2. tie → higher severity (P0 > P1 > P2 > P3)
+ *   3. tie → lexicographically earliest agent
+ *   4. tie → first-seen
+ *
+ * Score = severityWeight(severity) * confidence.
+ *
+ * No external deps. CommonJS to match the rest of scripts/lib/.
+ */
+
+'use strict';
+
+const SEVERITY_RANK = { P0: 4, P1: 3, P2: 2, P3: 1 };
+const DEFAULT_WEIGHTS = Object.freeze({ P0: 8, P1: 4, P2: 2, P3: 1 });
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} file
+ * @property {number} [line]
+ * @property {string} rule_id
+ * @property {'P0'|'P1'|'P2'|'P3'} severity
+ * @property {string} summary
+ * @property {string} [evidence]
+ * @property {string} [agent]
+ * @property {number} [confidence]
+ * @property {string[]} [merged_from]
+ */
+
+/**
+ * @typedef {Object} AggregateResult
+ * @property {Finding[]} findings
+ * @property {Object<string, number>} byRule
+ * @property {Object<string, number>} bySeverity
+ * @property {Object<string, number>} byFile
+ * @property {number} total
+ * @property {number} duplicates
+ */
+
+/**
+ * @typedef {Object} AggregateOptions
+ * @property {number} [topN]
+ * @property {Object<string, number>} [severityWeights]
+ * @property {(a: Finding, b: Finding) => Finding} [merge]
+ */
+
+function normalizePath(p) {
+  return String(p).replace(/\\/g, '/').toLowerCase();
+}
+
+let _confidenceWarningEmitted = false;
+
+function clampConfidence(c) {
+  if (c === undefined || c === null) return 1;
+  if (typeof c !== 'number' || Number.isNaN(c)) return 1;
+  if (c < 0) {
+    if (!_confidenceWarningEmitted) {
+      process.emitWarning('audit-aggregator: confidence < 0 clamped to 0', 'AuditAggregator');
+      _confidenceWarningEmitted = true;
+    }
+    return 0;
+  }
+  if (c > 1) {
+    if (!_confidenceWarningEmitted) {
+      process.emitWarning('audit-aggregator: confidence > 1 clamped to 1', 'AuditAggregator');
+      _confidenceWarningEmitted = true;
+    }
+    return 1;
+  }
+  return c;
+}
+
+/**
+ * Compute score for a finding.
+ *
+ * @param {Finding} f
+ * @param {Object<string, number>} weights
+ * @returns {number}
+ */
+function score(f, weights) {
+  const w = (weights && weights[f.severity]) ?? DEFAULT_WEIGHTS[f.severity] ?? 0;
+  return w * clampConfidence(f.confidence);
+}
+
+function validateFinding(f, idx) {
+  if (!f || typeof f !== 'object') {
+    throw new TypeError(`audit-aggregator: input[${idx}] is not an object`);
+  }
+  if (typeof f.file !== 'string' || f.file.length === 0) {
+    throw new TypeError(`audit-aggregator: input[${idx}].file is required (non-empty string)`);
+  }
+  if (typeof f.rule_id !== 'string' || f.rule_id.length === 0) {
+    throw new TypeError(`audit-aggregator: input[${idx}].rule_id is required (non-empty string)`);
+  }
+  if (!(f.severity in SEVERITY_RANK)) {
+    throw new TypeError(
+      `audit-aggregator: input[${idx}].severity must be P0|P1|P2|P3 (got ${JSON.stringify(f.severity)})`,
+    );
+  }
+}
+
+function dedupKey(f) {
+  return `${normalizePath(f.file)}::${f.line ?? 0}::${f.rule_id}`;
+}
+
+function defaultMerge(a, b) {
+  // Higher confidence wins.
+  const ca = clampConfidence(a.confidence);
+  const cb = clampConfidence(b.confidence);
+  if (ca !== cb) return ca > cb ? a : b;
+  // Higher severity wins.
+  const ra = SEVERITY_RANK[a.severity];
+  const rb = SEVERITY_RANK[b.severity];
+  if (ra !== rb) return ra > rb ? a : b;
+  // Lexicographic agent.
+  const aa = a.agent ?? '';
+  const ab = b.agent ?? '';
+  if (aa !== ab) return aa < ab ? a : b;
+  // First-seen wins (a is by convention the existing entry).
+  return a;
+}
+
+/**
+ * Aggregate findings.
+ *
+ * @param {Finding[]} input
+ * @param {AggregateOptions} [opts]
+ * @returns {AggregateResult}
+ */
+function aggregate(input, opts = {}) {
+  if (!Array.isArray(input)) {
+    throw new TypeError('audit-aggregator: input must be an array');
+  }
+  // Reset the once-per-call warning flag so a second call can warn again.
+  _confidenceWarningEmitted = false;
+  const merge = typeof opts.merge === 'function' ? opts.merge : defaultMerge;
+  const weights = { ...DEFAULT_WEIGHTS, ...(opts.severityWeights || {}) };
+
+  /** @type {Map<string, Finding>} */
+  const byKey = new Map();
+  let duplicates = 0;
+  for (let i = 0; i < input.length; i++) {
+    validateFinding(input[i], i);
+    const f = { ...input[i] };
+    const key = dedupKey(f);
+    if (byKey.has(key)) {
+      duplicates += 1;
+      const existing = byKey.get(key);
+      const winner = merge(existing, f);
+      const loser = winner === existing ? f : existing;
+      const mergedFrom = new Set(winner.merged_from || []);
+      if (existing.agent && existing !== winner) mergedFrom.add(existing.agent);
+      if (loser.agent && loser !== winner) mergedFrom.add(loser.agent);
+      // Combine prior merged_from too.
+      for (const a of (loser.merged_from || [])) mergedFrom.add(a);
+      winner.merged_from = Array.from(mergedFrom);
+      byKey.set(key, winner);
+    } else {
+      byKey.set(key, f);
+    }
+  }
+
+  const findings = Array.from(byKey.values()).map((f) => ({ ...f, _score: score(f, weights) }));
+  findings.sort((a, b) => {
+    if (a._score !== b._score) return b._score - a._score;
+    const ra = SEVERITY_RANK[a.severity];
+    const rb = SEVERITY_RANK[b.severity];
+    if (ra !== rb) return rb - ra;
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    return (a.line ?? 0) - (b.line ?? 0);
+  });
+  // Strip the internal _score field before returning.
+  for (const f of findings) delete f._score;
+
+  const truncated = typeof opts.topN === 'number' && opts.topN >= 0
+    ? findings.slice(0, opts.topN)
+    : findings;
+
+  /** @type {Record<string, number>} */
+  const byRule = {};
+  /** @type {Record<string, number>} */
+  const bySeverity = { P0: 0, P1: 0, P2: 0, P3: 0 };
+  /** @type {Record<string, number>} */
+  const byFile = {};
+  for (const f of truncated) {
+    byRule[f.rule_id] = (byRule[f.rule_id] ?? 0) + 1;
+    bySeverity[f.severity] += 1;
+    const k = normalizePath(f.file);
+    byFile[k] = (byFile[k] ?? 0) + 1;
+  }
+
+  return {
+    findings: truncated,
+    byRule,
+    bySeverity,
+    byFile,
+    total: truncated.length,
+    duplicates,
+  };
+}
+
+module.exports = {
+  aggregate,
+  score,
+  normalizePath,
+  dedupKey,
+  defaultMerge,
+  DEFAULT_WEIGHTS,
+  SEVERITY_RANK,
+};