@usefragments/core 1.2.0 → 1.4.0

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-BQQTMGLA.js";
+} from "../chunk-57QDBEHQ.js";
 import {
   legacySeverityLevelSchema,
   severityLevelSchema,

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-DYSirwJu.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-DxdJV6lx.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/agent-format.test.ts

@@ -136,7 +136,7 @@ describe("buildAgentFormat", () => {
     });
   });
 
-  it("fails an inert zero-rule scan with score zero and a machine-readable reason", () => {
+  it("marks an inert zero-rule scan indeterminate without inventing a score", () => {
     const agentFormat = buildAgentFormat({
       filesScanned: 1,
       findings: [],
@@ -151,7 +151,8 @@ describe("buildAgentFormat", () => {
 
     expect(agentFormat).toMatchObject({
       passed: false,
-      score: 0,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"],
       integrity: {
         rulesLoaded: 0,
         healthy: false,
@@ -159,10 +160,57 @@ describe("buildAgentFormat", () => {
         reasons: ["no_enforceable_rules"],
       },
     });
-    expect(agentFormat.summary).toContain("no_enforceable_rules");
+    expect(agentFormat).not.toHaveProperty("score");
+    expect(agentFormat.summary).toContain("zero_rules_loaded");
     expect(() => agentFormatSchema.parse(agentFormat)).not.toThrow();
   });
 
+  it("rejects invalid determinate and indeterminate field combinations", () => {
+    const determinate = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: HEALTHY_INTEGRITY,
+    });
+    const indeterminate = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: {
+        rulesLoaded: 0,
+        status: "inert",
+        healthy: false,
+        inert: true,
+        reasons: ["no_enforceable_rules"],
+      },
+    });
+
+    expect(agentFormatSchema.safeParse({ ...determinate, score: undefined }).success).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...determinate,
+        status: "indeterminate",
+        reasons: ["zero_rules_loaded"],
+      }).success
+    ).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...determinate, reasons: [] }).success).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...indeterminate, passed: true }).success).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...indeterminate, score: 0 }).success).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({ ...indeterminate, reasons: ["no_enforceable_rules"] }).success
+    ).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...determinate,
+        integrity: { ...determinate.integrity, rulesLoaded: 0 },
+      }).success
+    ).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...indeterminate,
+        integrity: { ...indeterminate.integrity, rulesLoaded: 1 },
+      }).success
+    ).toBe(false);
+  });
+
   it("validates the structured error envelope against the shared agent output schema", () => {
     expect(() =>
       agentOutputSchema.parse({
@@ -172,4 +220,28 @@ describe("buildAgentFormat", () => {
       })
     ).not.toThrow();
   });
+
+  it("preserves additive Run provenance and verdict through typed parsing", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: HEALTHY_INTEGRITY,
+      provenance: {
+        runId: "run_0123456789ab",
+        fcid: "a".repeat(64),
+        scope: { method: "full", gitOk: true },
+        engineVersion: `sha256:${"b".repeat(64)}`,
+        scopeHash: "c".repeat(64),
+        inputFilesHash: "d".repeat(64),
+      },
+      verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },
+    });
+
+    const parsed = agentOutputSchema.parse(agentFormat);
+
+    expect(parsed).toMatchObject({
+      provenance: { runId: "run_0123456789ab", scope: { method: "full", gitOk: true } },
+      verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },
+    });
+  });
 });

package/src/agent-format.ts

@@ -14,9 +14,12 @@ export interface BuildAgentFormatInput {
   maxFindings?: number;
   includeEvidence?: boolean;
   includeFindings?: boolean;
+  provenance?: NonNullable<AgentFormat["provenance"]>;
+  verdict?: NonNullable<AgentFormat["verdict"]>;
 }
 
 export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
+  const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
   const integrityFailed = !input.integrity.healthy || input.integrity.inert;
   const score = integrityFailed ? 0 : scoreFindings(input.findings);
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
@@ -29,6 +32,7 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
     severity: finding.severity,
     level: severityLevel(finding.severity),
     message: finding.message,
+    evidenceGrade: finding.evidenceGrade,
     evidence: input.includeEvidence ? finding.evidence : [],
     plan: planForFinding(finding),
   }));
@@ -38,13 +42,13 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
   // `passed:false`.
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
 
-  return {
+  const shared = {
     schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
-    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
-    score,
-    summary: integrityFailed
-      ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}`
-      : agentSummary(input.findings.length, input.filesScanned, score),
+    summary: zeroRulesLoaded
+      ? "indeterminate; zero_rules_loaded"
+      : integrityFailed
+        ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}`
+        : agentSummary(input.findings.length, input.filesScanned, score),
     integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
@@ -70,6 +74,24 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
           })),
         }
       : {}),
+    ...(input.provenance ? { provenance: input.provenance } : {}),
+    ...(input.verdict ? { verdict: input.verdict } : {}),
+  };
+
+  if (zeroRulesLoaded) {
+    return {
+      ...shared,
+      integrity: { ...input.integrity, rulesLoaded: 0 },
+      passed: false,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"],
+    };
+  }
+
+  return {
+    ...shared,
+    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
+    score,
   };
 }
 

package/src/constants.ts

@@ -30,6 +30,9 @@ export const BRAND = {
   /** CLI command name (e.g., "fragments") */
   cliCommand: "fragments",
 
+  /** Full user-facing CLI invocation for copy printed to end users (e.g., "npx @usefragments/cli") */
+  cliInvocation: "npx @usefragments/cli",
+
   /** Directory for storing fragments, registry, and cache */
   dataDir: ".fragments",
 

package/src/evidence.ts

@@ -0,0 +1,27 @@
+/** Stable evidence grades shared by scanners, renderers, Inspect, and Cloud. */
+export type EvidenceGrade =
+  | "none"
+  | "runtime_advisory"
+  | "provenance_bound"
+  | "source_backed"
+  | "receipt_backed";
+
+export const EVIDENCE_ORDER = [
+  "none",
+  "runtime_advisory",
+  "provenance_bound",
+  "source_backed",
+  "receipt_backed",
+] as const satisfies readonly EvidenceGrade[];
+
+/** Only source-backed or receipt-backed claims may block a write or CI gate. */
+export function canBlock(grade: EvidenceGrade): boolean {
+  return EVIDENCE_ORDER.indexOf(grade) >= EVIDENCE_ORDER.indexOf("source_backed");
+}
+
+export type InspectClaimTier = "advisory" | "local_only" | "team_ci" | "receipt";
+
+export interface InspectClaim {
+  tier: InspectClaimTier;
+  text: string;
+}

package/src/facts/builders.ts

@@ -464,6 +464,7 @@ export function makeTokenDefinitionFact(input: {
   location?: TokenDefinitionFact["location"];
   category?: TokenDefinitionFact["category"];
   referenceFormat?: TokenDefinitionFact["referenceFormat"];
+  sourceNames?: TokenDefinitionFact["sourceNames"];
 }): TokenDefinitionFact {
   return {
     id: factId("token_definition", { name: input.name }),
@@ -473,6 +474,7 @@ export function makeTokenDefinitionFact(input: {
     ...(input.location ? { location: input.location } : {}),
     category: input.category,
     referenceFormat: input.referenceFormat,
+    ...(input.sourceNames?.length ? { sourceNames: [...input.sourceNames] } : {}),
   };
 }
 
@@ -618,7 +620,7 @@ export function makeUsagePropResolvedFact(input: {
 export function makeUsageInlineStyleFact(input: {
   nodeId: FactId;
   property: string;
-  valueKind: "static" | "number" | "css-variable";
+  valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
 }): UsageInlineStyleFact {
   return {

package/src/facts/fact-index.ts

@@ -59,7 +59,7 @@ function logicalComponentId(componentId: ComponentId): ComponentId {
 
 function logicalFactForComparison(fact: Fact): Record<string, unknown> {
   if (fact.kind === "token_definition") {
-    const { location: _location, ...logicalFact } = fact;
+    const { location: _location, sourceNames: _sourceNames, ...logicalFact } = fact;
     return logicalFact;
   }
   if (fact.kind === "jsx_import_path_preferred") {
@@ -113,8 +113,12 @@ export class FactIndex {
   private readonly facts = new Map<FactId, Fact>();
   private readonly idsByKind = new Map<FactKind, Set<FactId>>();
   private readonly idsByComponent = new Map<ComponentId, Set<FactId>>();
+  private readonly tokenBySymbol = new Map<string, TokenDefinitionFact>();
 
   add(fact: Fact): void {
+    if (fact.kind === "token_definition") {
+      this.indexTokenSymbols(fact);
+    }
     const existing = this.facts.get(fact.id);
     if (existing) {
       if (
@@ -122,7 +126,7 @@ export class FactIndex {
         canonicalJson(logicalFactForComparison(fact))
       ) {
         console.warn(
-          `FactIndex: conflicting facts for id ${fact.id} — keeping first fact, skipping ${describeFactForConflict(fact)}`
+          `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`
         );
       }
       return;
@@ -346,12 +350,28 @@ export class FactIndex {
     list: (): TokenDefinitionFact[] => this.byKind("token_definition"),
     byCategory: (category: TokenDefinitionFact["category"]): TokenDefinitionFact[] =>
       this.byKind("token_definition").filter((t) => t.category === category),
+    symbolExists: (name: string): boolean => this.tokenBySymbol.has(name),
+    definitionForSymbol: (name: string): TokenDefinitionFact | undefined =>
+      this.tokenBySymbol.get(name),
   };
 
   // ---------------------------------------------------------------------
   // Internals
   // ---------------------------------------------------------------------
 
+  private indexTokenSymbols(fact: TokenDefinitionFact): void {
+    const legacyScssAlias =
+      fact.referenceFormat === "scss-var" && fact.name.startsWith("--")
+        ? `$${fact.name.slice(2)}`
+        : fact.referenceFormat === "scss-var" && fact.name.startsWith("$")
+          ? `--${fact.name.slice(1)}`
+          : undefined;
+    for (const symbol of [fact.name, ...(fact.sourceNames ?? []), legacyScssAlias]) {
+      if (!symbol) continue;
+      if (!this.tokenBySymbol.has(symbol)) this.tokenBySymbol.set(symbol, fact);
+    }
+  }
+
   private byComponentOfKind<F extends Fact>(componentId: ComponentId, kind: FactKind): F[] {
     const ids = this.idsByComponent.get(logicalComponentId(componentId));
     if (!ids) return [];

package/src/facts/facts.test.ts

@@ -485,7 +485,7 @@ describe("FactIndex — query layer", () => {
 
     expect(warn).toHaveBeenCalledWith(
       expect.stringMatching(
-        /conflicting facts.*kind=token_definition location=tokens\/theme\.css:4:1/
+        /conflicting facts.*keeping kind=token_definition location=tokens\/base\.css:2:1, skipping kind=token_definition location=tokens\/theme\.css:4:1/
       )
     );
     expect(ix.get(first.id)).toEqual(first);

package/src/facts/types.ts

@@ -217,6 +217,8 @@ export interface TokenDefinitionFact extends BaseFact {
    * Absent on legacy/hand-built facts, which are treated as safe.
    */
   referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+  /** Original authored spellings retained before parser normalization. */
+  sourceNames?: string[];
 }
 
 export interface TailwindPaletteAllowFact extends BaseFact {
@@ -308,7 +310,20 @@ export interface UsageInlineStyleFact extends BaseFact {
   kind: "usage_inline_style";
   nodeId: FactId;
   property: string;
-  valueKind: "static" | "number" | "css-variable";
+  /**
+   * How the extractor resolved the value:
+   * - `static`       — a string literal (`"#f00"`, `"12px"`).
+   * - `number`       — a numeric literal (React treats it as `px`).
+   * - `css-variable` — a `var(--token)` reference; rules treat it as a token.
+   * - `dynamic-raw`  — a value constructed at runtime whose *static* fragments
+   *   unambiguously begin a raw color literal (`` `#${red}` ``,
+   *   `` `rgb(${r},${g},${b})` ``, `"#" + hex`). `value` carries a reconstructed
+   *   skeleton with each interpolation rendered as `‹expr›`. Detect-only: a rule
+   *   may flag it as a raw color but must NEVER attach a deterministic fix
+   *   (the value is partly runtime). Only color-shaped dynamic values ever
+   *   surface as facts — a non-color dynamic value stays opaque.
+   */
+  valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
 }
 

package/src/index.ts

@@ -7,6 +7,10 @@
 export { BRAND, DEFAULTS } from "./constants.js";
 export type { Brand, Defaults } from "./constants.js";
 
+// Evidence vocabulary (wire-stable, browser-safe, shared with Inspect).
+export { EVIDENCE_ORDER, canBlock } from "./evidence.js";
+export type { EvidenceGrade, InspectClaim, InspectClaimTier } from "./evidence.js";
+
 // Conform engine contract (shared across extract engine, mcp tool, surfaces)
 export type {
   ConformChange,

package/src/rules/__tests__/fix-emission-invariant.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+
+import { FactIndex } from "../../facts/fact-index.js";
+import {
+  makeGovernanceRuleConfigFact,
+  makeScaleFact,
+  makeScaleValueFact,
+  makeStyleDeclarationFact,
+  makeStyleFontSizeScaleFact,
+  makeStylePropertyScaleFact,
+  makeStyleRawColorForbiddenFact,
+  makeStyleRawDimensionForbiddenFact,
+  makeTokenDefinitionFact,
+} from "../../facts/builders.js";
+import type { Finding, FindingFix } from "../types.js";
+import { RULES } from "../index.js";
+import { tokenSymbolsInText } from "../utils.js";
+
+describe("proof-carrying fix invariant", () => {
+  it("runs every rule and downgrades every token fix when its registry is poisoned", () => {
+    const ix = buildFixtureCorpus();
+    const fullRegistryFindings = runEveryRule(ix);
+    const fullRegistryFixes = tokenFixes(fullRegistryFindings);
+
+    expect(fullRegistryFindings.every((finding) => finding.evidenceGrade === "source_backed")).toBe(
+      true
+    );
+    expect(fullRegistryFixes).toHaveLength(5);
+    expect(fullRegistryFixes.every(({ fix }) => fix.deterministic === true)).toBe(true);
+
+    ix.tokens.symbolExists = () => false;
+    const poisonedFindings = runEveryRule(ix);
+    const poisonedFixes = tokenFixes(poisonedFindings);
+
+    expect(poisonedFixes).toHaveLength(fullRegistryFixes.length);
+    expect(
+      poisonedFixes.map(({ finding, fix }) => ({
+        ruleId: finding.ruleId,
+        fix: withoutDeterminism(fix),
+      }))
+    ).toEqual(
+      fullRegistryFixes.map(({ finding, fix }) => ({
+        ruleId: finding.ruleId,
+        fix: withoutDeterminism(fix),
+      }))
+    );
+    expect(poisonedFixes.filter(({ fix }) => fix.deterministic === true)).toEqual([]);
+    expect(
+      poisonedFixes.every(
+        ({ finding }) =>
+          typeof finding.attributes?.downgradeReason === "string" &&
+          finding.attributes.downgradeReason.includes("absent token symbol")
+      )
+    ).toBe(true);
+  });
+
+  it("downgrades an exact dimension match whose token has no directly applicable form", () => {
+    const ix = buildFixtureCorpus("dtcg");
+    const dimension = RULES.find((rule) => rule.id === "styles/no-raw-dimensions")
+      ?.run(ix)
+      .find((finding) => finding.fix);
+
+    expect(dimension?.fix?.deterministic).toBe(false);
+    expect(dimension?.attributes?.downgradeReason).toContain(
+      "token reference is not directly applicable"
+    );
+  });
+});
+
+function runEveryRule(ix: FactIndex): Finding[] {
+  const visited: string[] = [];
+  const findings = RULES.flatMap((rule) => {
+    visited.push(rule.id);
+    return rule.run(ix);
+  });
+  expect(visited).toEqual(RULES.map((rule) => rule.id));
+  return findings;
+}
+
+function tokenFixes(findings: readonly Finding[]) {
+  return findings.flatMap((finding) => {
+    const fix = finding.fix;
+    if (!fix) return [];
+    const symbols = tokenSymbolsInText(replacementText(fix));
+    return symbols.length > 0 ? [{ finding, fix, symbols }] : [];
+  });
+}
+
+function replacementText(fix: FindingFix): string {
+  if (fix.kind === "replaceStyleValue") return fix.value;
+  if (fix.kind === "replaceImport" || fix.kind === "replaceComponent") return fix.to;
+  if (fix.kind === "replaceClassToken") return fix.to ?? "";
+  return typeof fix.value === "string" ? fix.value : "";
+}
+
+function withoutDeterminism(fix: FindingFix): Omit<FindingFix, "deterministic"> {
+  const { deterministic: _deterministic, ...rest } = fix;
+  return rest;
+}
+
+function buildFixtureCorpus(radiusReferenceFormat: "css-var" | "dtcg" = "css-var"): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany([
+    makeTokenDefinitionFact({
+      name: "--proof-color",
+      value: "#123456",
+      category: "color",
+      referenceFormat: "css-var",
+      sourceNames: ["--proof-color"],
+    }),
+    makeTokenDefinitionFact({
+      name: "--proof-space",
+      value: "8px",
+      category: "spacing",
+      referenceFormat: "css-var",
+      sourceNames: ["--proof-space"],
+    }),
+    makeTokenDefinitionFact({
+      name: "--proof-radius",
+      value: "4px",
+      category: "radius",
+      referenceFormat: radiusReferenceFormat,
+      sourceNames: ["--proof-radius"],
+    }),
+    makeTokenDefinitionFact({
+      name: "--proof-font",
+      value: "16px",
+      category: "typography",
+      referenceFormat: "css-var",
+      sourceNames: ["--proof-font"],
+    }),
+    makeTokenDefinitionFact({
+      name: "--proof-dual",
+      value: "8px",
+      category: "spacing",
+      referenceFormat: "scss-var",
+      sourceNames: ["--proof-dual", "$proof-dual"],
+    }),
+    makeStyleRawColorForbiddenFact({ except: [], prefer: "token", severity: "error" }),
+    makeStyleRawDimensionForbiddenFact({
+      appliesTo: ["border-radius"],
+      prefer: "token",
+      severity: "error",
+    }),
+    makeScaleFact({ name: "space", unit: "px" }),
+    makeScaleValueFact({ scale: "space", value: 8 }),
+    makeStylePropertyScaleFact({ property: "margin", scale: "space", severity: "error" }),
+    makeScaleFact({ name: "type", unit: "px" }),
+    makeScaleValueFact({ scale: "type", value: 16 }),
+    makeStyleFontSizeScaleFact({ scale: "type", severity: "error" }),
+    makeGovernanceRuleConfigFact({
+      ruleId: "tokens/require-dual-fallback",
+      enabled: true,
+      severity: "error",
+    }),
+    declaration("color", "#123456", 1),
+    declaration("border-radius", "4px", 2),
+    declaration("margin", "8px", 3),
+    declaration("font-size", "16px", 4),
+    declaration("gap", "var(--proof-dual)", 5),
+  ]);
+  return ix;
+}
+
+function declaration(property: string, value: string, line: number) {
+  return makeStyleDeclarationFact({
+    file: "fixture.scss",
+    selector: ".fixture",
+    declarationPath: `.fixture/${property}`,
+    property,
+    value,
+    location: { file: "fixture.scss", line, column: 1 },
+  });
+}

package/src/rules/__tests__/tokens-require-dual-fallback.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeContractTokenFact,
+  makeStyleCssVarsMustBeDefinedFact,
+  makeStyleDeclarationFact,
+  makeTokenDefinitionFact,
+} from "../../index.js";
+import { ruleTokensCssVarsMustBeDefined } from "../tokens-css-vars-must-be-defined.js";
+import { ruleTokensRequireDualFallback } from "../tokens-require-dual-fallback.js";
+
+function declaration(value: string) {
+  return makeStyleDeclarationFact({
+    file: "src/app.scss",
+    selector: ".app",
+    declarationPath: "0",
+    property: "padding",
+    value,
+    location: { file: "src/app.scss", line: 1, column: 0 },
+  });
+}
+
+function index(...facts: Parameters<FactIndex["addMany"]>[0][]): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: { "tokens/require-dual-fallback": { enabled: true, severity: "error" } },
+    })
+  );
+  for (const group of facts) ix.addMany(group);
+  return ix;
+}
+
+describe("tokens/require-dual-fallback trust floor", () => {
+  it("stays silent for an unregistered token and never invents its Sass symbol (§1)", () => {
+    const ix = index([
+      makeStyleCssVarsMustBeDefinedFact({ severity: "warn" }),
+      makeContractTokenFact({ name: "--fui-space-2" }),
+      declaration("var(--fui-space-9)"),
+    ]);
+
+    expect(ruleTokensRequireDualFallback(ix)).toEqual([]);
+    const undefinedFindings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(undefinedFindings).toHaveLength(1);
+    expect(JSON.stringify(undefinedFindings)).not.toContain("$fui-space-9");
+  });
+
+  it("emits a deterministic fix only for a registered Sass variable and rescans clean (§2)", () => {
+    const token = makeTokenDefinitionFact({
+      name: "$fui-space-2",
+      value: "8px",
+      category: "spacing",
+      referenceFormat: "scss-var",
+    });
+    const ix = index([token, declaration("var(--fui-space-2)")]);
+
+    expect(ruleTokensRequireDualFallback(ix)).toMatchObject([
+      {
+        fix: {
+          kind: "replaceStyleValue",
+          value: "var(--fui-space-2, $fui-space-2)",
+          deterministic: true,
+        },
+      },
+    ]);
+
+    const rescanned = index([token, declaration("var(--fui-space-2, $fui-space-2)")]);
+    expect(ruleTokensRequireDualFallback(rescanned)).toEqual([]);
+  });
+
+  it("keeps the finding but emits no fix for a CSS-only token (§2)", () => {
+    const ix = index([
+      makeTokenDefinitionFact({
+        name: "--fui-color-accent",
+        value: "#2563eb",
+        category: "color",
+        referenceFormat: "css-var",
+      }),
+      declaration("var(--fui-color-accent)"),
+    ]);
+
+    const findings = ruleTokensRequireDualFallback(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].fix).toBeUndefined();
+    expect(findings[0].message).toContain("No matching SCSS variable was found");
+    expect(JSON.stringify(findings[0])).not.toContain("$fui-color-accent)");
+  });
+});