stylelint-plugin-rhythmguard 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.7.0] - 2026-09-17
+
+### Added
+
+- Every rule accepts `note`, a sentence of up to 200 characters appended to each finding after the built-in text: `... (nearest: 12px or 16px). See docs/spacing.md for approved exceptions.` The built-in text is unchanged, so tooling that matches on it keeps working. Stylelint and ESLint rules alike. ([#134](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/134))
+
+### Changed
+
+- `prefer-token` names the token it would write and where it was read from: `Unexpected raw scale value "12px". Use var(--space-3) (src/tokens.css).` The origin is the linted stylesheet, the `tokenMapFile` or the Tailwind config; an inline `tokenMap` entry is named without one, and a negative literal as `calc(-1 * var(--space-3))`. When no mapping holds the value the message says `No known token holds this value; use the nearest token or add one.` It said `Use design tokens for scale decisions.` in every case. ([#133](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/133))
+- `use-scale` and `no-offscale-transform` with `fixWith: "token"` append `var(--space-3) holds 12px.` when exactly one token qualifies, so the message names what the fix writes. ([#133](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/133))
+- `tailwind-class-use-scale` names the utility classes for the two nearest steps, with their px values, and its fix writes the utility class instead of an on-scale arbitrary value: `p-[13px]` reads `Use "p-3" (12px) or "p-4" (16px)` and becomes `p-3`; `md:-m-[13px]!` becomes `md:-m-3!`; `p-[0.8125rem]` becomes `p-3`. The class number is the snapped value divided by the new `spacingUnit` option (4px, Tailwind's `--spacing`); when it is not a quarter step the fix keeps the arbitrary form, and `spacingUnit: false` keeps it always. The audit's Tailwind findings carry the same text and `fixedToken`. ([#132](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/132))
+- The release workflow verifies and publishes on GitHub-hosted runners, and the post-publish smoke runs there too. The first 3.7.0 release waited 24 hours for a self-hosted runner that never registered and was cancelled; a release no longer depends on the farm. Pushes and pull requests still use it.
+
+## [3.6.0] - 2026-09-09
+
+### Added
+
+- **Token chains.** The audit follows every spacing-named custom property through `var()` references to its terminal values and reports, in `contracts.tokens.chains` and a Markdown section, whether each resolves on the scale, off it, to an undeclared token or a cycle, to several lengths at once (themes), to a computed expression, or to a non-length. Fallbacks are honoured; declarations from token sources and installed packages count. This is the measurement token-layered systems need, where a literal scan finds almost nothing. ([#110](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/110))
+- `rhythmguard fix <dir> --value <length> --to <replacement>` replaces one spacing literal everywhere it appears, matching by px, keeping the sign, never touching token definitions, token functions or non-spacing properties; dry run until `--write`, idempotent, SCSS through `postcss-scss`. `--decided` executes every `snap` decision whose `to` names the replacement. `postcss` is now a declared runtime dependency (the rules always received its AST; the codemod parses files itself).
+- `use-scale` and `no-offscale-transform` accept `fixWith: "token"`: autofix writes `var(--name)` when exactly one custom property holds the snapped value in the literal's own unit, read from the stylesheet, `scaleSources`, the config file's token sources and installed token packages, and the literal otherwise. A rem literal never becomes a px token, and two tokens with the same value never become a guess. Default stays `"value"`; the default flips in 4.0.
+- **Decisions.** A `decisions` section in `.rhythmguardrc.json` records what a team decided about each off-scale value: `adopt` (part of the scale, optionally naming the token it should become), `allow` (intentional, optionally on some properties only), `snap` (a slip to fix) or `undecided`. Adopted and allowed values stop being findings in the Stylelint rules and the audit alike; values match by px so `10px` and `0.625rem` are one decision. `rhythmguard audit --plan` proposes the section from the current findings and keeps decisions already made. The audit reports counts in `contracts.decisions`. Rules accept `decisions: false` to ignore the section. Docs: `docs/AUDIT.md#decisions`.
+
+### Changed
+
+- Baselines key findings by content (rule, file, property, value, occurrence) instead of line and column, so moving or reformatting code no longer produces matching "new" and "resolved" pairs while a second identical off-scale declaration is still new. Baseline files are `formatVersion: 2`; version 1 files still compare and upgrade on the next `--write-baseline`. Text, Markdown and GitHub output lead with `Since baseline: N resolved, M new`.
+
+### Fixed
+
+- Token values of the form `calc(var(--x) * 2)` are no longer read as a 2px token; the calc forms require a unit on the factor, as in Radix's `calc(4px * var(--scaling))`.
+- `prefer-token` autofix writes a negative token as `calc(-1 * var(--token))`. It wrote `-var(--token)`, which is not valid CSS.
+
 ## [3.5.0] - 2026-09-08
 
 ### Fixed

package/CONTRIBUTING.md

@@ -27,7 +27,7 @@ npm ci
 npm test
 ```
 
-Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` and take about ten seconds. They are grouped by what they prove:
+Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about ten seconds. They are grouped by what they prove:
 
 | Folder | Proves | Run one |
 | --- | --- | --- |
@@ -58,8 +58,11 @@ npm run test:compat-floor      # Stylelint 16.0.0, the oldest supported
 npm run test:pack-smoke        # pack the tarball and install it in a temp project
 npm run scales:validate        # community scale JSON
 npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
+npm run build:agents           # after editing the block in docs/FOR_AGENTS.md
 ```
 
+The local gate runs on whatever Node you have installed; CI runs Node 20 and 22. Node 20.19 is the floor, so avoid features that arrived in Node 21 or later. Glob patterns for `node --test` were one such feature, and they took a release run down.
+
 If your shell's npm registry is overridden by a corporate `.npmrc`, add `--registry https://registry.npmjs.org` to `npm ci` and prefix `test:pack-smoke` with `npm_config_registry=https://registry.npmjs.org`.
 
 ### Pull requests from forks
@@ -78,7 +81,7 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
 
 **The benchmark is the regression suite for real code.** If your change alters findings on any benchmark repository, `npm run bench:quiet -- --check` fails and prints the diff. Review it. If the new findings are right, run `npm run bench:quiet -- --update-snapshots`, commit `benchmarks/quiet/snapshots/`, and say in the PR why they are right.
 
-**Fixes are deterministic.** Autofix snaps to the nearest scale step or to an explicit token map. It never guesses a token. Keep that property.
+**Fixes are deterministic.** Autofix snaps to the nearest scale step, or with `fixWith: "token"` writes the one custom property that holds that value in the same unit. It never guesses a token: two candidates, a unit mismatch or a Sass variable all mean the literal is written instead. `rhythmguard fix` follows the same rule. Keep that property.
 
 **Prose without em dashes.** House style, applied to docs and messages alike.
 
@@ -88,14 +91,14 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
 - Minor: new options, presets, sources, or behaviour that does not change existing reports.
 - Major: any change to default reports for existing configs, to autofix behaviour, or to exported entry points.
 
-`configs/recommended`, `configs/strict`, `configs/tailwind` and `configs/embed` stay stable within a major. The `embed` config's shape is frozen for 2.x because shared configs depend on it.
+`configs/recommended`, `configs/strict`, `configs/tailwind`, `configs/motion` and `configs/embed` stay stable within a major. The `embed` config's shape is frozen within a major because shared configs depend on it.
 
 ## Compatibility
 
 - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
 - Node `>=20.19.0`.
 - CommonJS and ESM entry points; every export has a declaration under `types/`.
-- One runtime dependency, `known-css-properties`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here.
+- Three runtime dependencies: `known-css-properties`, `postcss` and `postcss-value-parser`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here. `test/contracts/architecture.test.js` fails if a runtime import is not declared.
 
 ## Review
 
@@ -103,7 +106,7 @@ The maintainer aims to respond to issues and PRs within a week. Small PRs merge
 
 ## Releases
 
-Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
+Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies the matrix and publishes through npm trusted publishing (OIDC), on GitHub-hosted runners so a release does not depend on the self-hosted farm. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
 
 ## Benchmarking performance
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=7" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=10" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -7,13 +7,13 @@
 Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=370)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 
-Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
+Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS and SCSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
 
-What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). Pair it with a color linter if you need one; do not expect one tool to do both. SCSS is audited when `postcss-scss` is installed.
+What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). Pair it with a color linter if you need one; do not expect one tool to do both.
 
 ## Start here
 
@@ -81,11 +81,9 @@ npx rhythmguard audit ./src --since-baseline --fail-on-new-drift
 npx rhythmguard audit ./src --format github
 ```
 
-The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, and GitHub Actions annotations. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md).
+The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md).
 
-`npx rhythmguard init` writes a starter config for your stack. `npx rhythmguard doctor` checks the setup.
-
-A README badge comes from the same audit: `--format badge` writes a shields.io endpoint document, see [`docs/CI_ADOPTION.md`](./docs/CI_ADOPTION.md#5-show-a-badge).
+`npx rhythmguard audit ./src --plan` turns the report into a proposed `decisions` section (adopt a value, allow it, or snap it), and `npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write` executes one decision as one reviewable change; see [decisions](docs/AUDIT.md#decisions). `npx rhythmguard init` writes a starter config for your stack, and `init --agents all` installs the coding-agent instructions. `npx rhythmguard doctor` checks the setup.
 
 ## Guides
 
@@ -99,11 +97,11 @@ A README badge comes from the same audit: `--format badge` writes a shields.io e
 - [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
 - [Architecture](docs/ARCHITECTURE.md): the layers, the rule kit, the invariants and where each is enforced
 - [Product direction](docs/STRATEGY_2026-09.md)
-- Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
+- Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/), a simplified re-implementation for trying values in the browser; the real rules run under Node ([#57](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/57) tracks bundling them)
 
 ## Compatibility
 
-Stylelint 16 and 17. Node 20.19 or newer. One runtime dependency (`known-css-properties`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
+Stylelint 16 and 17. Node 20.19 or newer. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
 
 ## Contributing and support
 

package/SECURITY.md

@@ -4,8 +4,9 @@
 
 | Version | Supported |
 | --- | --- |
-| 2.x | Yes |
-| < 2.0 | No, upgrade to 2.x |
+| 3.x | Yes |
+| 2.x | Security fixes only until 2027-03-01 |
+| < 2.0 | No, upgrade to 3.x |
 
 ## Reporting a Vulnerability
 

package/agents/claude-code/SKILL.md

@@ -11,7 +11,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/agents/copilot/copilot-instructions.md

@@ -6,7 +6,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/agents/cursor/rhythmguard.mdc

@@ -12,7 +12,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -147,6 +147,7 @@
   },
   "dependencies": {
     "known-css-properties": "^0.37.0",
+    "postcss": "^8.4.0",
     "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {

package/src/audit/args.js

@@ -29,6 +29,7 @@ const OPTIONS = [
   { flag: '--json', kind: 'flag', help: 'Alias for --format json', apply: (p) => { p.format = 'json'; } },
   { flag: '--markdown', kind: 'flag', help: 'Alias for --format markdown', apply: (p) => { p.format = 'markdown'; } },
   { flag: '--schema', kind: 'flag', help: 'Print the audit JSON schema and exit', apply: (p) => { p.schema = true; p.format = 'json'; } },
+  { flag: '--plan', kind: 'flag', help: 'Print a proposed decisions section for .rhythmguardrc.json: one entry per off-scale value', apply: (p) => { p.plan = true; } },
   { flag: '--output', kind: 'value', value: '<file>', help: 'Write json, markdown, html or badge output to a file',
     apply: (p, raw) => { p.outputPath = parsePathOption(raw, '--output'); setFrom(p, 'outputPath'); } },
   { flag: '--config', kind: 'value', value: '<file>', help: 'Load audit config (default: .rhythmguardrc.json when present)',

package/src/audit/baseline.js

@@ -4,6 +4,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { formatPath } = require('./shared');
 
+/**
+ * Baseline keys name a finding by what it is, not where it sits: rule, type,
+ * file, property (or Tailwind class), value, and the occurrence index among
+ * identical findings in that file. Inserting a comment above a declaration no
+ * longer turns it into one "resolved" and one "new"; adding a second identical
+ * off-scale declaration still counts as new. Version 1 baselines keyed by line
+ * and column are still compared with the key they were written with.
+ */
+const BASELINE_FORMAT_VERSION = 2;
+
 function applyBaselineComparison(report, baselinePath) {
   const resolvedPath = path.resolve(process.cwd(), baselinePath);
   if (!fs.existsSync(resolvedPath)) {
@@ -12,11 +22,15 @@ function applyBaselineComparison(report, baselinePath) {
 
   const baseline = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
   const baselineFindings = Array.isArray(baseline.findings) ? baseline.findings : [];
-  const baselineKeys = new Set(baselineFindings.map((finding) => finding.key || createFindingKey(finding)));
+  const legacy = baseline.formatVersion !== BASELINE_FORMAT_VERSION;
   const currentFindings = getAllFindings(report);
-  const currentKeys = new Set(currentFindings.map(createFindingKey));
-  const newFindings = currentFindings.filter((finding) => !baselineKeys.has(createFindingKey(finding)));
-  const resolvedFindings = baselineFindings.filter((finding) => !currentKeys.has(finding.key || createFindingKey(finding)));
+  const currentKeys = legacy
+    ? new Map(currentFindings.map((finding) => [finding, createLegacyFindingKey(finding)]))
+    : assignFindingKeys(currentFindings);
+  const baselineKeys = new Set(baselineFindings.map((finding) => finding.key || createLegacyFindingKey(finding)));
+  const currentKeySet = new Set(currentKeys.values());
+  const newFindings = currentFindings.filter((finding) => !baselineKeys.has(currentKeys.get(finding)));
+  const resolvedFindings = baselineFindings.filter((finding) => !currentKeySet.has(finding.key || createLegacyFindingKey(finding)));
 
   report.baseline = {
     baselineFindings: baselineFindings.length,
@@ -31,14 +45,16 @@ function applyBaselineComparison(report, baselinePath) {
 
 function writeBaseline(report, baselinePath) {
   const resolvedPath = path.resolve(process.cwd(), baselinePath);
+  const findings = getAllFindings(report);
+  const keys = assignFindingKeys(findings);
   fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
   fs.writeFileSync(
     resolvedPath,
     `${JSON.stringify({
       createdAt: new Date().toISOString(),
       directory: report.directory,
-      findings: getAllFindings(report).map(toBaselineFinding),
-      formatVersion: 1,
+      findings: findings.map((finding) => toBaselineFinding(finding, keys.get(finding))),
+      formatVersion: BASELINE_FORMAT_VERSION,
       summary: {
         scaleCleanliness: report.scaleCleanliness,
         totalFindings: report.totalWarnings,
@@ -60,12 +76,13 @@ function getAllFindings(report) {
   ];
 }
 
-function toBaselineFinding(finding) {
+function toBaselineFinding(finding, key) {
   return {
     column: finding.column,
     file: finding.file,
-    key: createFindingKey(finding),
+    key,
     line: finding.line,
+    property: finding.property || undefined,
     rule: finding.rule,
     text: finding.text,
     token: finding.token,
@@ -74,7 +91,33 @@ function toBaselineFinding(finding) {
   };
 }
 
-function createFindingKey(finding) {
+function findingIdentity(finding) {
+  return [
+    finding.rule || '',
+    finding.type || '',
+    finding.file || '',
+    finding.property || finding.token || '',
+    finding.value || finding.rawValue || '',
+  ].join('\u001f');
+}
+
+/** Content keys for a set of findings: identity plus the occurrence index in source order. */
+function assignFindingKeys(findings) {
+  const ordered = [...findings].sort((a, b) =>
+    String(a.file).localeCompare(String(b.file)) || (a.line || 0) - (b.line || 0) || (a.column || 0) - (b.column || 0));
+  const seen = new Map();
+  const keys = new Map();
+  for (const finding of ordered) {
+    const identity = findingIdentity(finding);
+    const occurrence = seen.get(identity) || 0;
+    seen.set(identity, occurrence + 1);
+    keys.set(finding, `${identity}\u001f${occurrence}`);
+  }
+  return keys;
+}
+
+/** The version 1 key: position-based, kept so existing baseline files keep working. */
+function createLegacyFindingKey(finding) {
   return [
     finding.rule || '',
     finding.type || '',
@@ -105,10 +148,11 @@ function getAuditFailures(report, parsed) {
 }
 
 module.exports = {
+  BASELINE_FORMAT_VERSION,
   applyBaselineComparison,
-  createFindingKey,
+  assignFindingKeys,
+  createLegacyFindingKey,
   getAllFindings,
   getAuditFailures,
-  toBaselineFinding,
   writeBaseline,
 };

package/src/audit/codemod.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const postcss = require('postcss');
+const valueParser = require('postcss-value-parser');
+const { PROPERTY_GROUP_PATTERNS } = require('../core/css-vocabulary');
+const { numbersEqual, parseLengthToken, toPx } = require('../core/length');
+const { negateReplacement } = require('../core/token-index');
+const { isTokenFunction, propertyMatches, walkRootValueNodes } = require('../core/value-nodes');
+const { formatPath } = require('./shared');
+const { isCssFile, isScssFile, walkFiles } = require('./scan/files');
+const { resolveScssSyntax } = require('./scan/stylesheets');
+
+/**
+ * The targeted codemod: one value, one replacement, reviewable as one change.
+ * It walks declaration values the way the rules do, so `10px` inside `110px`,
+ * inside `var(--x, 10px)`, on a non-spacing property or in a token definition
+ * is never touched. Matching is by px, so `0.625rem` is the same value as
+ * `10px`. The sign is kept: a negative literal becomes a negated replacement.
+ */
+const TOKEN_FUNCTIONS = ['var', 'theme', 'token'];
+const ANY_TOKEN = /./;
+
+function replaceLength(root, { baseFontSize = 16, properties = null, px, replacement }) {
+  const patterns = properties && properties.length > 0
+    ? properties.map((property) => property.toLowerCase())
+    : PROPERTY_GROUP_PATTERNS.spacing;
+  const changes = [];
+
+  root.walkDecls((decl) => {
+    const prop = decl.prop.toLowerCase();
+    if (prop.startsWith('--') || prop.startsWith('$') || !propertyMatches(prop, patterns)) {
+      return;
+    }
+    const parsed = valueParser(decl.value);
+    let changed = false;
+    walkRootValueNodes(parsed, (node) => {
+      if (node.type === 'function') {
+        // true skips the children: nothing inside var()/theme()/token() is ours to rewrite
+        return isTokenFunction(node, TOKEN_FUNCTIONS, ANY_TOKEN);
+      }
+      if (node.type !== 'word') {
+        return false;
+      }
+      const length = parseLengthToken(node.value);
+      if (!length || length.number === 0 || length.unit === '%' || length.unit === '') {
+        return false;
+      }
+      const nodePx = toPx(Math.abs(length.number), length.unit, baseFontSize);
+      if (nodePx === null || !numbersEqual(nodePx, px)) {
+        return false;
+      }
+      const to = length.number < 0 ? negateReplacement(replacement) : replacement;
+      changes.push({
+        column: (decl.source && decl.source.start ? decl.source.start.column : 1) + declarationValueOffset(decl) + node.sourceIndex,
+        from: node.value,
+        line: decl.source && decl.source.start ? decl.source.start.line : 1,
+        property: decl.prop,
+        to,
+      });
+      node.value = to;
+      changed = true;
+      return false;
+    });
+    if (changed) {
+      decl.value = parsed.toString();
+    }
+  });
+
+  return changes;
+}
+
+function declarationValueOffset(decl) {
+  const raws = decl.raws || {};
+  const between = typeof raws.between === 'string' ? raws.between : ': ';
+  return decl.prop.length + between.length;
+}
+
+function parseStylesheet(filePath, source) {
+  if (isScssFile(filePath)) {
+    const syntaxPath = resolveScssSyntax();
+    if (!syntaxPath) {
+      return null;
+    }
+    return postcss.parse(source, { from: filePath, syntax: require(syntaxPath) });
+  }
+  return postcss.parse(source, { from: filePath });
+}
+
+/**
+ * Apply one replacement across a directory. Dry run unless `write`; returns
+ * the per-file changes and which files were skipped (unparseable, or SCSS
+ * without postcss-scss).
+ */
+function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties = null, px, replacement, write = false }) {
+  const rootDir = path.resolve(process.cwd(), dir);
+  const files = walkFiles(rootDir, ignorePatterns).cssFiles.filter(isCssFile).sort();
+  const results = [];
+  const skipped = [];
+  for (const filePath of files) {
+    const source = fs.readFileSync(filePath, 'utf8');
+    let root;
+    try {
+      root = parseStylesheet(filePath, source);
+    } catch {
+      skipped.push({ file: formatPath(filePath), reason: 'could not parse' });
+      continue;
+    }
+    if (!root) {
+      skipped.push({ file: formatPath(filePath), reason: 'install postcss-scss to rewrite SCSS' });
+      continue;
+    }
+    const changes = replaceLength(root, { baseFontSize, properties, px, replacement });
+    if (changes.length === 0) {
+      continue;
+    }
+    if (write) {
+      fs.writeFileSync(filePath, root.toString());
+    }
+    results.push({ changes, file: formatPath(filePath) });
+  }
+  return { results, skipped };
+}
+
+module.exports = {
+  replaceLength,
+  runCodemod,
+};

package/src/audit/config.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { normalizeDecisions } = require('../core/decisions');
 const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
@@ -58,6 +59,7 @@ function loadAuditConfig(parsed) {
 
   return {
     audit,
+    decisions: config.decisions,
     file: formatPath(resolvedPath),
     rootDir: path.dirname(resolvedPath),
   };
@@ -76,6 +78,7 @@ function applyAuditConfig(parsed, configResult) {
 
   if (!configResult) {
     next.tokenSources = normalizeCliTokenSources(parsed.tokenSources, parsed.tokenSourceFormat);
+    next.decisions = [];
     delete next.cliOptions;
     return next;
   }
@@ -113,6 +116,8 @@ function applyAuditConfig(parsed, configResult) {
     return parseScale(String(value));
   });
 
+  next.decisions = normalizeDecisions(configResult.decisions, { baseFontSize: next.baseFontSize });
+
   delete next.cliOptions;
   return next;
 }

package/src/audit/contract.js

@@ -365,6 +365,7 @@ function toAuditContractReport(report) {
       scanScope: report.scanScope.mode,
     },
     contracts: {
+      decisions: report.decisions || null,
       motion: report.motion,
       scale: {
         cleanliness: report.scaleCleanliness,

package/src/audit/decisions.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const { decisionFor } = require('../core/decisions');
+const { formatLength, nearestScaleValues, parseLengthToken, toPx } = require('../core/length');
+
+/**
+ * Decisions applied to audit findings, and the plan that proposes them.
+ * Adopted and allowed values are removed from the findings; snap and undecided
+ * ones stay. The plan lists every off-scale value seen, keeping decisions
+ * already written and adding `undecided` entries for the rest.
+ */
+function findingPx(finding, baseFontSize) {
+  const raw = finding.value || finding.rawValue;
+  const parsed = typeof raw === 'string' ? parseLengthToken(raw.trim()) : null;
+  return parsed ? toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize) : null;
+}
+
+function findingProperty(finding) {
+  return finding.property || (finding.token ? 'class-string' : null);
+}
+
+function applyDecisions({ baseFontSize, cssFindings, decisions, tailwindFindings }) {
+  if (!decisions || decisions.length === 0) {
+    return { cssFindings, suppressed: 0, summary: null, tailwindFindings };
+  }
+  let suppressed = 0;
+  const keep = (finding) => {
+    if (finding.type !== 'off-scale' && !finding.token) {
+      return true;
+    }
+    const px = findingPx(finding, baseFontSize);
+    const decision = px === null ? null : decisionFor(px, findingProperty(finding), decisions);
+    if (decision && (decision.decision === 'adopt' || decision.decision === 'allow')) {
+      suppressed += 1;
+      return false;
+    }
+    return true;
+  };
+  const nextCss = cssFindings.filter(keep);
+  const nextTailwind = tailwindFindings.filter(keep);
+  const summary = { adopt: 0, allow: 0, snap: 0, undecided: 0 };
+  for (const decision of decisions) summary[decision.decision] += 1;
+  return { cssFindings: nextCss, suppressed, summary: { ...summary, suppressed }, tailwindFindings: nextTailwind };
+}
+
+/**
+ * One proposed entry per distinct off-scale px value: the most common spelling,
+ * how often it occurs, the properties it sits on, the two nearest scale steps,
+ * and the decision so far (`undecided` for anything nobody has looked at).
+ */
+function buildDecisionPlan({ baseFontSize, decisions, offScaleFindings, scale }) {
+  const groups = new Map();
+  for (const finding of offScaleFindings) {
+    const px = findingPx(finding, baseFontSize);
+    if (px === null) continue;
+    const key = String(px);
+    const group = groups.get(key) || { count: 0, properties: new Map(), px, spellings: new Map() };
+    group.count += 1;
+    const spelling = (finding.value || finding.rawValue).trim();
+    group.spellings.set(spelling, (group.spellings.get(spelling) || 0) + 1);
+    const property = findingProperty(finding);
+    if (property) group.properties.set(property, (group.properties.get(property) || 0) + 1);
+    groups.set(key, group);
+  }
+
+  const mostCommon = (map) => [...map.entries()].sort((a, b) => b[1] - a[1]).map(([name]) => name);
+  const scalePx = Array.isArray(scale) ? scale.map(Number).filter(Number.isFinite) : [];
+  const nearestFor = (px) => {
+    const nearest = nearestScaleValues(px, scalePx);
+    return nearest ? [formatLength(nearest.lower, 'px'), formatLength(nearest.upper, 'px')] : [];
+  };
+
+  const entries = [];
+  const decided = new Set();
+  for (const decision of decisions || []) {
+    const group = groups.get(String(decision.px));
+    decided.add(String(decision.px));
+    entries.push({
+      value: decision.value,
+      decision: decision.decision,
+      ...(decision.as ? { as: decision.as } : {}),
+      ...(decision.reason ? { reason: decision.reason } : {}),
+      ...(decision.properties ? { properties: decision.properties } : {}),
+      count: group ? group.count : 0,
+      nearest: nearestFor(decision.px),
+    });
+  }
+  for (const [key, group] of groups) {
+    if (decided.has(key)) continue;
+    entries.push({
+      value: mostCommon(group.spellings)[0],
+      decision: 'undecided',
+      count: group.count,
+      properties: mostCommon(group.properties).slice(0, 3),
+      nearest: nearestFor(group.px),
+    });
+  }
+  entries.sort((a, b) => b.count - a.count || String(a.value).localeCompare(String(b.value)));
+  return entries;
+}
+
+module.exports = {
+  applyDecisions,
+  buildDecisionPlan,
+};

package/src/audit/render-github.js

@@ -4,9 +4,12 @@ const { getAllFindings } = require('./baseline');
 
 function renderGithub(report) {
   const findings = getAllFindings(report);
-  const lines = findings.map((finding) =>
+  const lines = report.baseline
+    ? [`::notice title=Rhythmguard audit::Since baseline: ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new`]
+    : [];
+  lines.push(...findings.map((finding) =>
     `::warning file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'rhythmguard')}::${escapeGithubData(finding.text || '')}`,
-  );
+  ));
   const findingWord = findings.length === 1 ? 'finding' : 'findings';
   const fileWord = report.filesWithIssues === 1 ? 'file' : 'files';
   lines.push(