@usefragments/core 1.5.2 → 1.7.0

package/src/governance-integrity.ts

@@ -4,7 +4,7 @@
  *
  * The load-bearing distinction is **enabled ≠ armed**. A rule can be `enabled`
  * in the policy yet inert because it has no vocabulary to measure against:
- * `components/prefer-library` with no effective canonical source enforces
+ * canonical-component rules with no effective canonical source enforce
  * nothing; `tokens/css-vars-must-be-defined` with an empty token vocabulary
  * enforces nothing. This module derives, per rule *family*, whether the family
  * is armed (has both an enabled rule AND the vocabulary/signal it needs), then
@@ -18,14 +18,26 @@
  */
 
 import type { CanonicalSource, GovernanceConfig, GovernanceSeverity } from "./governance.js";
+import {
+  normalizePolicyExcludes,
+  policyExcludeMatchesPath,
+  type PolicyExclude,
+} from "./policy-exclude.js";
 import { compileGlobalGovernanceFacts } from "./facts/index.js";
+import type { FactConflict } from "./facts/index.js";
+import { RULE_FAMILY_IDS } from "./rules/families.js";
 import { FRAGMENTS_INTERNAL_RULE_IDS, RULE_TIER } from "./rules/tiers.js";
 import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 
 export type GovernanceIntegrityStatus = "healthy" | "degraded" | "inert";
 
-export type InertConfigDiagnosticKind = "orphan-scale" | "unconsumed-key";
-export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005";
+export type InertConfigDiagnosticKind =
+  | "orphan-scale"
+  | "unconsumed-key"
+  | "unmatched-exclude"
+  | "colliding-record"
+  | "overridden-record-severity";
+export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005" | "FUI9006" | "FUI9007" | "FUI9008";
 
 export interface InertConfigDiagnostic {
   code: InertConfigDiagnosticCode;
@@ -107,7 +119,7 @@ export function isEffectiveCanonicalSource(source: CanonicalSource): boolean {
 }
 
 /**
- * Whether `components/prefer-library`'s effective options carry a real component
+ * Whether a canonical-component rule's effective options carry a real component
  * vocabulary: at least one canonical mapping, or at least one effective
  * canonical source. Accepts the raw fact `options` bag (values are `unknown`).
  */
@@ -126,18 +138,27 @@ export function hasEffectiveComponentVocabulary(
 /**
  * Compile the policy to effective per-rule configs, keyed by rule id. Reuses the
  * fact compiler so the effective enabled/severity/options match exactly what the
- * scan engine sees (including the canonicalSources → prefer-library injection).
+ * scan engine sees (including canonicalSources → component-rule injection).
  */
 function effectiveRuleConfigs(
   policy: GovernanceConfig | undefined
 ): Map<string, EffectiveRuleConfig> {
   const configs = new Map<string, EffectiveRuleConfig>();
-  for (const fact of compileGlobalGovernanceFacts(policy)) {
-    if (fact.kind !== "governance_rule_config") continue;
-    configs.set(fact.ruleId, {
-      enabled: fact.enabled,
-      severity: fact.severity,
-      options: fact.options,
+  const facts = compileGlobalGovernanceFacts(policy);
+  for (const fact of facts) {
+    if (fact.kind === "governance_rule_config") {
+      configs.set(fact.ruleId, {
+        enabled: fact.enabled,
+        severity: fact.severity,
+        options: fact.options,
+      });
+    }
+  }
+  const cssVarsPolicy = facts.find((fact) => fact.kind === "style_css_vars_must_be_defined");
+  if (cssVarsPolicy?.kind === "style_css_vars_must_be_defined") {
+    configs.set("tokens/css-vars-must-be-defined", {
+      enabled: true,
+      severity: cssVarsPolicy.severity,
     });
   }
   return configs;
@@ -152,10 +173,13 @@ function dedupe(values: string[]): string[] {
   return [...new Set(values)];
 }
 
-const RULE_FAMILY_IDS = new Set(["tokens/hardcoded-values", "components/usage", "a11y/wcag"]);
 const CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
 const RECOGNIZED_RULE_IDS = new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
-const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options"]);
+// `exclude` is consumed by the scan's finding-override pass (it scopes the rule off
+// the matching paths and reports each drop in the ignored accounting). It was absent
+// from this allow-set, so a working key was diagnosed as inert — the diagnostic was
+// wrong, not the config.
+const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options", "exclude"]);
 
 const PASSTHROUGH_KEYS = [
   {
@@ -195,7 +219,7 @@ const PASSTHROUGH_KEYS = [
   },
   {
     path: ["govern", "ci"],
-    keys: ["failOnWarnings"],
+    keys: ["failOnWarnings", "failOnInert"],
   },
 ] as const;
 
@@ -237,6 +261,232 @@ function unconsumedKeyDiagnostic(path: readonly (string | number)[]): InertConfi
   };
 }
 
+/**
+ * Config-record fact kinds: the policy facts that a `govern.*` record compiles into,
+ * paired with the config section that authored them, the authored record that produced
+ * them, and the identity keys their fact id is built from.
+ *
+ * `record` is load-bearing, not decoration. Several kinds in one section key on nothing
+ * (`style.rawColors.forbid`, `style.cssVars.mustBeDefined`, …) or on the same fields
+ * (`jsx.importPath.prefer` and `jsx.component.prefer` both on from/to), so a
+ * section-only diagnostic path makes two DIFFERENT collisions look like one — and the
+ * (code, path) dedupe every consumer runs then discards all but the last, which is the
+ * silence this diagnostic exists to end.
+ *
+ * Deliberately NOT the whole `PolicyFact` union — `token_definition` and
+ * `contract_token` are compiled from token *files*, not authored config records, and
+ * their collisions belong to the token-catalog diagnostics channel. Naming a duplicate
+ * token as a config defect would misattribute it and drown the real signal.
+ */
+const CONFIG_RECORD_FACT_KINDS: Readonly<
+  Record<string, { section: string; record: string; keys: string[] }>
+> = {
+  scale: { section: "govern.scales", record: "scale", keys: ["name"] },
+  scale_value: { section: "govern.scales", record: "scale.values", keys: ["scale", "value"] },
+  style_raw_color_forbidden: {
+    section: "govern.styles",
+    record: "style.rawColors.forbid",
+    keys: [],
+  },
+  style_raw_dimension_forbidden: {
+    section: "govern.styles",
+    record: "style.rawDimensions.forbid",
+    keys: [],
+  },
+  style_property_scale: {
+    section: "govern.styles",
+    record: "style.rawSpacing.mustMatchScale",
+    keys: ["property"],
+  },
+  style_font_size_scale: {
+    section: "govern.styles",
+    record: "style.fontSize.mustMatchScale",
+    keys: [],
+  },
+  style_css_vars_must_be_defined: {
+    section: "govern.styles",
+    record: "style.cssVars.mustBeDefined",
+    keys: [],
+  },
+  jsx_unknown_props_forbidden: {
+    section: "govern.jsx",
+    record: "jsx.unknownProps.forbid",
+    keys: [],
+  },
+  jsx_inline_style_forbidden_raw: {
+    section: "govern.jsx",
+    record: "jsx.inlineStyle.forbidRaw",
+    keys: ["property"],
+  },
+  jsx_import_path_preferred: {
+    section: "govern.jsx",
+    record: "jsx.importPath.prefer",
+    keys: ["from", "to", "imported"],
+  },
+  jsx_component_preferred: {
+    section: "govern.jsx",
+    record: "jsx.component.prefer",
+    keys: ["from", "to"],
+  },
+  prop_value_avoided: {
+    section: "govern.components",
+    record: "prop.value.avoid",
+    keys: ["componentId", "prop", "value"],
+  },
+  prop_value_forbidden: {
+    section: "govern.components",
+    record: "prop.value.forbid",
+    keys: ["componentId", "prop", "value", "pathPattern"],
+  },
+  a11y_name_required: {
+    section: "govern.components",
+    record: "a11y.requireName",
+    keys: ["componentId"],
+  },
+  tailwind_palette_allow: {
+    section: "govern.tailwind",
+    record: "palette.allow",
+    keys: [],
+  },
+  tailwind_palette_deny: { section: "govern.tailwind", record: "palette.deny", keys: [] },
+  tailwind_unknown_class_enabled: {
+    section: "govern.tailwind",
+    record: "unknownClass",
+    keys: [],
+  },
+  governance_rule_config: { section: "govern.rules", record: "rule", keys: ["ruleId"] },
+};
+
+/** The authored settings a reader needs to see to tell two colliding records apart. */
+const COLLISION_DETAIL_KEYS = [
+  "severity",
+  "scale",
+  "prefer",
+  "enabled",
+  "appliesTo",
+  "except",
+  "properties",
+  "because",
+] as const;
+
+function renderFactFields(fact: Record<string, unknown>, keys: readonly string[]): string {
+  return keys
+    .filter((key) => fact[key] !== undefined)
+    .map((key) => `${key}=${Array.isArray(fact[key]) ? JSON.stringify(fact[key]) : fact[key]}`)
+    .join(" ");
+}
+
+/**
+ * Name a config record that the fact index dropped as a first-wins duplicate.
+ *
+ * This is the Layer-6 backstop, not the primary mechanism: merge-time displacement
+ * (`mergeGovernanceConfigs`) already makes the later record win for every shape it can
+ * key. What reaches here is a collision displacement could NOT resolve — two records
+ * that compile to one fact id from different channels (config vs bridge vs Cloud
+ * policy). The invariant it defends: a dropped policy fact is never silent.
+ *
+ * Returns `null` for non-config facts, so usage/token collisions stay on the internal
+ * debug channel.
+ */
+export function collidingRecordDiagnostic(conflict: FactConflict): InertConfigDiagnostic | null {
+  return collidingRecordDiagnostics([conflict])[0] ?? null;
+}
+
+/**
+ * Aggregate every observed collision into one diagnostic per colliding fact id.
+ *
+ * Three same-kind records on one fact id produce TWO conflicts (first-wins keeps the
+ * first and skips both others), and both render the same path. Emitting them separately
+ * meant the `(code, path)` dedupe every consumer runs kept only the last pair, so the
+ * intermediate record was dropped in silence — the same failure the per-kind path fixed
+ * one layer down. Aggregating names the count and lists every dropped setting, and one
+ * user edit still resolves the whole group.
+ */
+export function collidingRecordDiagnostics(
+  conflicts: readonly FactConflict[]
+): InertConfigDiagnostic[] {
+  const groups = new Map<
+    string,
+    { record: string; kept: string; dropped: string[]; keptFallback: string }
+  >();
+
+  for (const conflict of conflicts) {
+    const shape = CONFIG_RECORD_FACT_KINDS[conflict.kept.kind];
+    if (!shape || conflict.kept.kind !== conflict.skipped.kind) continue;
+
+    const keptFact = conflict.kept as unknown as Record<string, unknown>;
+    const skippedFact = conflict.skipped as unknown as Record<string, unknown>;
+    const identity = renderFactFields(keptFact, shape.keys);
+    // The record kind is part of the identity, not just the prose: two singleton-keyed
+    // kinds in one section would otherwise share a path and collapse under the (code,
+    // path) dedupe, dropping one collision silently.
+    const path = `${shape.section}[${identity ? `${shape.record} ${identity}` : shape.record}]`;
+    const group = groups.get(path) ?? {
+      record: shape.record,
+      kept: renderFactFields(keptFact, COLLISION_DETAIL_KEYS),
+      dropped: [],
+      keptFallback: "the first record",
+    };
+    const dropped = renderFactFields(skippedFact, COLLISION_DETAIL_KEYS);
+    group.dropped.push(dropped || `record ${group.dropped.length + 2}`);
+    groups.set(path, group);
+  }
+
+  return [...groups].map(([path, group]) => ({
+    code: "FUI9007" as const,
+    kind: "colliding-record" as const,
+    severity: "warn" as const,
+    path,
+    message:
+      `${path} has ${group.dropped.length + 1} \`${group.record}\` records that compile to the same policy fact — ` +
+      `enforcing ${group.kept || group.keptFallback} and dropping ${group.dropped.join("; ")}. ` +
+      "Author one record for this policy, or scope them apart, so the enforced setting is the one you can read.",
+  }));
+}
+
+/**
+ * The authored config record a policy fact was compiled from, or `null` when the fact
+ * did not come from a `govern.*` record (token facts, usage facts). One table, read by
+ * both the collision diagnostic and the override backstop below.
+ */
+export function configRecordShape(kind: string): { section: string; record: string } | null {
+  const shape = CONFIG_RECORD_FACT_KINDS[kind];
+  return shape ? { section: shape.section, record: shape.record } : null;
+}
+
+/**
+ * Name a `govern.rules` override that outranks the severity a policy record authored.
+ *
+ * The backstop for the path provenance cannot reach. Locally, presets are merged here,
+ * so a preset's broad rule entry is tagged and treated as a default — a user record's
+ * `severity: "error"` wins (report #2 B4). A Cloud-served policy arrives whole: no merge
+ * ran, nothing is tagged, and a broad `tokens/hardcoded-values` entry in it still
+ * displaces the severity a record next to it authored. That cannot be fixed at this
+ * boundary, so it is named instead. Silence is the defect; an unfixable case must at
+ * least speak.
+ */
+export function overriddenRecordSeverityDiagnostic(input: {
+  ruleId: string;
+  /** Config path of the override that won — `govern.rules[...]` or `govern.severity`. */
+  source: string;
+  section: string;
+  record: string;
+  authored: string;
+  enforced: string;
+}): InertConfigDiagnostic {
+  const path = `${input.section}[${input.record}]`;
+  return {
+    code: "FUI9008",
+    kind: "overridden-record-severity",
+    severity: "warn",
+    path,
+    message:
+      `${path} authored severity=${input.authored}, but ${input.source} enforces ` +
+      `severity=${input.enforced} on \`${input.ruleId}\`. The record's severity is not what ` +
+      "gates CI — drop the rule override, or author the record at the severity you want enforced.",
+  };
+}
+
 function collectStrippedKeys(
   authored: unknown,
   parsed: unknown,
@@ -369,6 +619,65 @@ export function detectUnconsumedConfigKeys(
   return stableConfigDiagnostics(diagnostics);
 }
 
+/** Every authored exclude in a policy, paired with the config path that declared it. */
+function authoredPolicyExcludes(
+  policy: GovernanceConfig | undefined
+): Array<{ path: string; scope: string; exclude: PolicyExclude }> {
+  const out: Array<{ path: string; scope: string; exclude: PolicyExclude }> = [];
+  const collect = (path: string, scope: string, raw: unknown) => {
+    for (const exclude of normalizePolicyExcludes(raw) ?? []) {
+      out.push({ path, scope, exclude });
+    }
+  };
+
+  (policy?.styles ?? []).forEach((record, index) => {
+    collect(`govern.styles[${index}].exclude`, record.kind, record.exclude);
+  });
+  (policy?.jsx ?? []).forEach((record, index) => {
+    collect(`govern.jsx[${index}].exclude`, record.kind, record.exclude);
+  });
+  for (const ruleId of Object.keys(policy?.rules ?? {}).sort()) {
+    const record = objectRecord(policy?.rules?.[ruleId]);
+    if (!record) continue;
+    collect(`govern.rules.${ruleId}.exclude`, ruleId, record.exclude);
+  }
+
+  return out;
+}
+
+/**
+ * Diagnose excludes that scope nothing: the key is consumed and the glob is valid, but
+ * it matched no scanned file, so it silently exempts nothing while reading as active
+ * policy. That is the same "declared ≠ armed" failure this module exists to name — a
+ * stale path after a refactor is the common cause.
+ *
+ * `scannedFiles` are repo-relative paths supplied by the caller; core never reads the
+ * filesystem. An empty scan (nothing to compare against) yields no diagnostics rather
+ * than flagging every exclude.
+ */
+export function detectUnmatchedPolicyExcludes(
+  policy: GovernanceConfig | undefined,
+  scannedFiles: readonly string[]
+): InertConfigDiagnostic[] {
+  if (scannedFiles.length === 0) return [];
+  const diagnostics: InertConfigDiagnostic[] = [];
+
+  for (const { path, scope, exclude } of authoredPolicyExcludes(policy)) {
+    if (scannedFiles.some((file) => policyExcludeMatchesPath(exclude, file))) continue;
+    diagnostics.push({
+      code: "FUI9006",
+      kind: "unmatched-exclude",
+      severity: "warn",
+      path,
+      message:
+        `${path} pattern "${exclude.glob}" matched no scanned file, so ${scope} is not ` +
+        "actually scoped by it. Correct the glob to a path this scan covers, or remove it.",
+    });
+  }
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
 interface ScaleBinding {
   label: string;
   mechanism: string;
@@ -468,28 +777,34 @@ export function evaluateGovernanceIntegrity(
   }
 
   // --- components family ----------------------------------------------------
-  const componentsConfig = configs.get("components/prefer-library");
+  const preferLibraryConfig = configs.get("components/prefer-library");
+  const shadowComponentConfig = configs.get("components/shadow-component");
   const confirmedBridges = input.policy?.canonicalBridges ?? [];
-  const componentsArmed =
-    confirmedBridges.length > 0 ||
-    (componentsConfig?.enabled === true &&
-      hasEffectiveComponentVocabulary(componentsConfig.options));
+  const componentRuleEnabled =
+    preferLibraryConfig?.enabled === true || shadowComponentConfig?.enabled === true;
+  const preferLibraryArmed =
+    preferLibraryConfig?.enabled === true &&
+    hasEffectiveComponentVocabulary(preferLibraryConfig.options);
+  const shadowComponentArmed =
+    shadowComponentConfig?.enabled === true &&
+    hasEffectiveComponentVocabulary(shadowComponentConfig.options);
+  const componentsArmed = confirmedBridges.length > 0 || preferLibraryArmed || shadowComponentArmed;
   const componentsFamily: GovernanceIntegrityFamily = {
     id: "components",
     armed: componentsArmed,
     rules: [
       ...(confirmedBridges.length > 0 ? ["imports/preferred-path"] : []),
-      ...(componentsConfig?.enabled === true ? ["components/prefer-library"] : []),
+      ...(preferLibraryConfig?.enabled === true ? ["components/prefer-library"] : []),
+      ...(shadowComponentConfig?.enabled === true ? ["components/shadow-component"] : []),
     ],
   };
   if (!componentsArmed) {
-    if (componentsConfig?.enabled === true) {
-      componentsFamily.reason =
-        "components/prefer-library enabled but no effective canonical source";
+    if (componentRuleEnabled) {
+      componentsFamily.reason = "component governance enabled but no effective canonical source";
       componentsFamily.remediation =
         "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     } else {
-      componentsFamily.reason = "components/prefer-library not enabled";
+      componentsFamily.reason = "canonical-component rules not enabled";
       componentsFamily.remediation =
         "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     }
@@ -541,7 +856,12 @@ export function evaluateGovernanceIntegrity(
   for (const ruleId of BLOCKING_RULE_ALLOWLIST) {
     const config = configs.get(ruleId);
     if (config?.enabled !== true) continue;
-    const familyArmed = ruleId === "components/prefer-library" ? componentsArmed : hygieneArmed;
+    const familyArmed =
+      ruleId === "components/prefer-library" || ruleId === "components/shadow-component"
+        ? componentsArmed
+        : ruleId === "tokens/css-vars-must-be-defined"
+          ? tokensArmed
+          : hygieneArmed;
     if (!familyArmed) continue;
     if (config.severity !== "error" && !failOnWarnings) continue;
     blockingRules.push(ruleId);

package/src/governance.ts

@@ -10,10 +10,18 @@ import type {
   PropDefinition,
 } from "./types.js";
 import { portableRepoPathError } from "./config-paths.js";
+import { policyExcludeSchema } from "./policy-exclude.js";
 
 export const governanceSeveritySchema = z.enum(["error", "warn", "info"]);
 export type GovernanceSeverity = z.infer<typeof governanceSeveritySchema>;
 
+/**
+ * Per-record path excludes. Scopes THIS policy record off the matching paths without
+ * hiding those paths from any other rule — an auditable exemption, not a baseline.
+ * Excluded findings are reported in the scan's ignored accounting with their reason.
+ */
+const recordExcludeSchema = policyExcludeSchema.optional();
+
 export const scaleGovernanceRecordSchema = z.object({
   kind: z.literal("scale").default("scale"),
   name: z.string().min(1).optional(),
@@ -28,6 +36,7 @@ const styleRawColorsForbidRecordSchema = z.object({
   except: z.array(z.string()),
   prefer: z.enum(["token", "css-variable"]),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleRawDimensionsForbidRecordSchema = z.object({
@@ -35,6 +44,7 @@ const styleRawDimensionsForbidRecordSchema = z.object({
   appliesTo: z.array(z.string().min(1)),
   prefer: z.enum(["token", "css-variable"]),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleRawSpacingMustMatchScaleRecordSchema = z.object({
@@ -42,17 +52,20 @@ const styleRawSpacingMustMatchScaleRecordSchema = z.object({
   scale: z.string().min(1),
   appliesTo: z.array(z.string().min(1)),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleFontSizeMustMatchScaleRecordSchema = z.object({
   kind: z.literal("style.fontSize.mustMatchScale"),
   scale: z.string().min(1),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleCssVarsMustBeDefinedRecordSchema = z.object({
   kind: z.literal("style.cssVars.mustBeDefined"),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 export const globalStyleGovernanceRecordSchema = z.discriminatedUnion("kind", [
@@ -66,12 +79,14 @@ export const globalStyleGovernanceRecordSchema = z.discriminatedUnion("kind", [
 const jsxUnknownPropsForbidRecordSchema = z.object({
   kind: z.literal("jsx.unknownProps.forbid"),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxInlineStyleForbidRawRecordSchema = z.object({
   kind: z.literal("jsx.inlineStyle.forbidRaw"),
   properties: z.array(z.string().min(1)),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxImportPathPreferRecordSchema = z.object({
@@ -81,6 +96,7 @@ const jsxImportPathPreferRecordSchema = z.object({
   imported: z.string().min(1).optional(),
   because: z.string().optional(),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxComponentPreferRecordSchema = z.object({
@@ -89,6 +105,7 @@ const jsxComponentPreferRecordSchema = z.object({
   to: z.string().min(1),
   because: z.string().optional(),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 export const globalJsxGovernanceRecordSchema = z.discriminatedUnion("kind", [
@@ -337,6 +354,7 @@ export const governanceConfigSchema = z
     ci: z
       .object({
         failOnWarnings: z.boolean().optional(),
+        failOnInert: z.boolean().optional(),
       })
       .passthrough()
       .optional(),
@@ -424,14 +442,82 @@ export interface GovernanceConfig {
   /** Ordered component-policy overrides selected by component identity fields. */
   overrides?: ComponentPolicyOverride[];
 
-  /** Governance CI rendering options, including whether warnings fail the CI verdict. */
+  /**
+   * Governance CI rendering options: `failOnWarnings` makes warning findings fail the
+   * `--ci` verdict, `failOnInert` makes inert-config diagnostics (FUI9004-FUI9008) fail
+   * it. Both are opt-in; `--allow-inert` bypasses the inert gates.
+   */
   ci?: {
     failOnWarnings?: boolean;
+    /**
+     * Fail the `--ci` verdict when the run reports inert-config diagnostics
+     * (FUI9004-FUI9008). Opt-in: the diagnostics themselves stay verdict-neutral,
+     * so a team can adopt the gate once its config is clean. `--allow-inert`
+     * bypasses it, like the governance-inert gate.
+     */
+    failOnInert?: boolean;
     [key: string]: unknown;
   };
   [key: string]: unknown;
 }
 
+/**
+ * Provenance for a `govern.rules` entry: was it authored by the user, or contributed by
+ * a preset?
+ *
+ * A preset's broad entry (`tokens/hardcoded-values: { enabled: true, severity: "warn" }`)
+ * and a user's identical one mean different things. The preset's is a **default** — it
+ * says what the family looks like when nobody has an opinion. The user's is an
+ * **override** — they typed it. After merge the two are indistinguishable by shape, so
+ * the enforcement pass was capping user-authored `govern.styles[].severity: "error"`
+ * records at the preset's `warn` and saying nothing (report #2 B4).
+ *
+ * A global symbol rather than a config key, deliberately: provenance must not be
+ * authorable (a user cannot claim their entry came from a preset), must not survive the
+ * JSON round-trip into a served Cloud policy (where it would be a lie — that path merges
+ * no presets), and must not appear in a config the user reads back. `Symbol.for` so the
+ * marker survives duplicate module instances.
+ */
+const PRESET_SOURCED_RULE = Symbol.for("@usefragments/core:preset-sourced-rule");
+
+/**
+ * Tag every entry of a preset's `govern.rules` map as preset-sourced. Non-object entries
+ * (the `"warn"` string shorthand) cannot carry a symbol and are passed through untagged —
+ * presets author the object form, so this is a documented floor, not a silent gap.
+ *
+ * **Non-enumerable**, which is the difference between "does not serialize" and "is not
+ * there". A symbol key already survives neither `JSON.stringify` nor `Object.keys`, but
+ * it does survive `toEqual` — so an enumerable marker turns every consumer that compares
+ * a composed rule config structurally into a failing test, for a property they cannot see
+ * and did not ask for. Fragments Cloud's own policy composer was the first to hit it.
+ * Read it through `isPresetSourcedRule`; nothing else should know it exists.
+ */
+export function markPresetSourcedRules(
+  rules: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!rules) return rules;
+  const out: Record<string, unknown> = {};
+  for (const [ruleId, entry] of Object.entries(rules)) {
+    out[ruleId] =
+      entry && typeof entry === "object" && !Array.isArray(entry)
+        ? Object.defineProperty({ ...(entry as Record<string, unknown>) }, PRESET_SOURCED_RULE, {
+            value: true,
+            enumerable: false,
+          })
+        : entry;
+  }
+  return out;
+}
+
+/** Whether a merged `govern.rules` entry came from a preset rather than the user. */
+export function isPresetSourcedRule(entry: unknown): boolean {
+  return (
+    !!entry &&
+    typeof entry === "object" &&
+    (entry as Record<symbol, unknown>)[PRESET_SOURCED_RULE] === true
+  );
+}
+
 type SeverityOption = {
   severity?: GovernanceSeverity;
 };