@boyingliu01/xp-gate 0.19.3 → 0.20.0

package/principles/rules/clean-code/deep-nesting.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const deepNestingRule: Rule = {
   id: 'clean-code.deep-nesting',
   name: 'Deep Nesting Rule',
-  threshold: config.rules['clean-code']['deep-nesting'].threshold ?? 4,
-  severity: config.rules['clean-code']['deep-nesting'].severity as Severity,
+  threshold: 4,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['deep-nesting'];
     
     try {
       interface TypedAdapter {
@@ -19,15 +19,15 @@ export const deepNestingRule: Rule = {
       const functions = typedAdapter.extractFunctions?.() || [];
       
       for (const func of functions) {
-        if (func.nestingDepth && func.nestingDepth > (config.rules['clean-code']['deep-nesting'].threshold as number)) {
+        if (func.nestingDepth && func.nestingDepth > (settings.threshold ?? 0)) {
           violations.push({
             file,
             line: func.startLine ?? func.line ?? 1,
             ruleId: 'clean-code.deep-nesting',
             message: `Function "${func.name}" has deep nesting: ${func.nestingDepth} levels (maximum: ${
-              config.rules['clean-code']['deep-nesting'].threshold
+              settings.threshold
             })`,
-            severity: config.rules['clean-code']['deep-nesting'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'warning'
           });
         }
       }

package/principles/rules/clean-code/god-class.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const godClassRule: Rule = {
   id: 'clean-code.god-class',
   name: 'God Class Rule',
-  threshold: config.rules['clean-code']['god-class'].threshold ?? 15,
-  severity: config.rules['clean-code']['god-class'].severity as Severity,
+  threshold: 15,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['god-class'];
     
     try {
       interface ClassObject {
@@ -35,15 +35,15 @@ export const godClassRule: Rule = {
           return true;
         }).length;
         
-        if (methodCount > (config.rules['clean-code']['god-class'].threshold as number)) {
+        if (methodCount > (settings.threshold ?? 0)) {
           violations.push({
             file,
             line: cls.line,
             ruleId: 'clean-code.god-class',
             message: `Class "${cls.name}" has too many methods: ${methodCount} (maximum: ${
-              config.rules['clean-code']['god-class'].threshold
+              settings.threshold
             })`,
-            severity: config.rules['clean-code']['god-class'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'warning'
           });
         }
       }

package/principles/rules/clean-code/large-file.ts

@@ -1,34 +1,38 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const largeFileRule: Rule = {
   id: 'clean-code.large-file',
   name: 'Large File Rule',
-  threshold: config.rules['clean-code']['large-file'].threshold ?? 500,
-  severity: config.rules['clean-code']['large-file'].severity as Severity,
+  // Static field mirrors the built-in default. The ENFORCED value comes from
+  // getActiveConfig() inside check(), so `.principlesrc` is honoured (#457).
+  threshold: 1150,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
-    
+    // Read the ACTIVE config per invocation. Snapshotting it at module load was
+    // #457: a project's `.principlesrc` threshold was parsed but never applied.
+    const settings = getActiveConfig().rules['clean-code']['large-file'];
+    const threshold = settings.threshold ?? 500;
+
     try {
       interface TypedAdapter {
         countLines?: (file: string) => number | undefined;
       }
       const typedAdapter = adapter as TypedAdapter;
       const lineCount = typedAdapter.countLines?.(file) ?? 0;
-      
-      if (lineCount > (config.rules['clean-code']['large-file'].threshold as number)) {
+
+      if (lineCount > threshold) {
         violations.push({
           file,
           line: 1,
           ruleId: 'clean-code.large-file',
-          message: `File is too large: ${lineCount} lines (maximum: ${config.rules['clean-code']['large-file'].threshold})`,
-          severity: config.rules['clean-code']['large-file'].severity as Severity
+          message: `File is too large: ${lineCount} lines (maximum: ${threshold})`,
+          severity: (settings.severity as Severity) ?? 'warning'
         });
       }
     } catch { }
-    
+
     return violations;
   }
 };

package/principles/rules/clean-code/long-function.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const longFunctionRule: Rule = {
   id: 'clean-code.long-function',
   name: 'Long Function Rule',
-  threshold: config.rules['clean-code']['long-function'].threshold ?? 50,
-  severity: config.rules['clean-code']['long-function'].severity as Severity,
+  threshold: 50,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['long-function'];
     
     try {
       interface FunctionObj {
@@ -28,15 +28,15 @@ export const longFunctionRule: Rule = {
       for (const func of functions) {
         const { name, startLine, length } = func;
         
-        if (length > (config.rules['clean-code']['long-function'].threshold as number)) {
+        if (length > (settings.threshold ?? 0)) {
           violations.push({
             file,
             line: startLine ?? 1,
             ruleId: 'clean-code.long-function',
             message: `Function "${name}" is too long: ${length} lines (maximum: ${
-              config.rules['clean-code']['long-function'].threshold
+              settings.threshold
             })`,
-            severity: config.rules['clean-code']['long-function'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'warning'
           });
         }
       }

package/principles/rules/clean-code/magic-numbers.ts

@@ -1,17 +1,19 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
+import { getActiveConfig } from '../../config';
 
-const config = getDefaultConfig();
-
-const EXCLUDED_NUMBERS = config.rules['clean-code']['magic-numbers'].exclude || [0, 1, -1, 2, 10, 100, 1000, 60, 24, 7, 30, 365, 256, 1024];
+const DEFAULT_EXCLUDED_NUMBERS = [0, 1, -1, 2, 10, 100, 1000, 60, 24, 7, 30, 365, 256, 1024];
 
 export const magicNumbersRule: Rule = {
   id: 'clean-code.magic-numbers',
   name: 'Magic Numbers Rule',
+  // Not config-derived: this rule reports every non-excluded literal, so the
+  // static field is an informational placeholder rather than an enforced bound.
   threshold: 10,
-  severity: config.rules['clean-code']['magic-numbers'].severity as Severity,
+  severity: 'info',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['magic-numbers'];
     
     try {
       interface NumberObject {
@@ -37,9 +39,10 @@ export const magicNumbersRule: Rule = {
         }
       } catch { }
       
+      const excludedNumbers = settings.exclude ?? DEFAULT_EXCLUDED_NUMBERS;
       const filteredNumbers = magicNumbers.filter(numObj => {
         const numValue = numObj.value;
-        return !EXCLUDED_NUMBERS.includes(numValue);
+        return !excludedNumbers.includes(numValue);
       });
       
       filteredNumbers.forEach(numObj => {
@@ -48,7 +51,7 @@ export const magicNumbersRule: Rule = {
           line: numObj.line,
           ruleId: 'clean-code.magic-numbers',
           message: `Potential magic number detected: ${numObj.value}. Consider using a named constant instead.`,
-          severity: config.rules['clean-code']['magic-numbers'].severity as Severity
+          severity: (settings.severity as Severity) ?? 'info'
         });
       });
       

package/principles/rules/clean-code/many-exports.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const manyExportsRule: Rule = {
   id: 'clean-code.many-exports',
   name: 'Many Exports Rule',
-  threshold: config.rules['clean-code']['many-exports'].threshold ?? 10,
-  severity: config.rules['clean-code']['many-exports'].severity as Severity,
+  threshold: 10,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['many-exports'];
 
     try {
       interface ExportObj {
@@ -22,7 +22,7 @@ export const manyExportsRule: Rule = {
       
       const typedAdapter = adapter as TypedAdapter;
       const exports = typedAdapter.extractExports ? typedAdapter.extractExports() : [];
-      const threshold = config.rules['clean-code']['many-exports'].threshold ?? 10;
+      const threshold = settings.threshold ?? 10;
       
       if (exports && exports.length > threshold) {
         violations.push({
@@ -30,7 +30,7 @@ export const manyExportsRule: Rule = {
           line: exports[0]?.line || 1,
           ruleId: 'clean-code.many-exports',
           message: `Module has too many exports: ${exports.length} (maximum: ${threshold}). Consider splitting into focused sub-modules.`,
-          severity: config.rules['clean-code']['many-exports'].severity as Severity
+          severity: (settings.severity as Severity) ?? 'warning'
         });
       }
     } catch { }

package/principles/rules/clean-code/missing-error-handling.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const missingErrorHandlingRule: Rule = {
   id: 'clean-code.missing-error-handling',
   name: 'Missing Error Handling Rule',
   threshold: 1,
-  severity: config.rules['clean-code']['missing-error-handling'].severity as Severity,
+  severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['missing-error-handling'];
     
     try {
       const typedAdapter = adapter as { extractFunctions?: () => Array<{name?: string; startLine?: number; line?: number; ioOperations?: string[]; hasTryCatch?: boolean;}> | undefined };
@@ -22,7 +22,7 @@ export const missingErrorHandlingRule: Rule = {
             line: func.startLine ?? func.line ?? 1,
             ruleId: 'clean-code.missing-error-handling',
             message: `Function "${func.name}" has IO operations (${func.ioOperations.join(', ')}) without error handling`,
-            severity: config.rules['clean-code']['missing-error-handling'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'warning'
           });
         }
       }

package/principles/rules/clean-code/too-many-params.ts

@@ -1,30 +1,30 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const tooManyParamsRule: Rule = {
   id: 'clean-code.too-many-params',
   name: 'Too Many Parameters Rule',
-  threshold: config.rules['clean-code']['too-many-params'].threshold ?? 7,
-  severity: config.rules['clean-code']['too-many-params'].severity as Severity,
+  threshold: 7,
+  severity: 'info',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['too-many-params'];
     
     try {
       const typedAdapter = adapter as { extractFunctions?: () => Array<{name?: string; startLine?: number; line?: number; paramCount?: number;}> | undefined };
       const functions = typedAdapter.extractFunctions?.() || [];
       
       for (const func of functions) {
-        if (func.paramCount && func.paramCount > (config.rules['clean-code']['too-many-params'].threshold as number)) {
+        if (func.paramCount && func.paramCount > (settings.threshold ?? 0)) {
           violations.push({
             file,
             line: func.startLine ?? func.line ?? 1,
             ruleId: 'clean-code.too-many-params',
             message: `Function "${func.name}" has too many parameters: ${func.paramCount} (maximum: ${
-              config.rules['clean-code']['too-many-params'].threshold
+              settings.threshold
             })`,
-            severity: config.rules['clean-code']['too-many-params'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'info'
           });
         }
       }

package/principles/rules/clean-code/unused-imports.ts

@@ -1,15 +1,15 @@
 import { Rule, Violation, Severity } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const unusedImportsRule: Rule = {
   id: 'clean-code.unused-imports',
   name: 'Unused Imports Rule',
   threshold: 1,
-  severity: config.rules['clean-code']['unused-imports'].severity as Severity,
+  severity: 'info',
   check: (file: string, adapter: unknown): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['clean-code']['unused-imports'];
     
     try {
       const typedAdapter = adapter as { imports?: Array<{name?: string; line?: number; used?: boolean; type?: string;}> | undefined };
@@ -22,7 +22,7 @@ export const unusedImportsRule: Rule = {
             line: imp.line ?? 1,
             ruleId: 'clean-code.unused-imports',
             message: `Unused import "${imp.name}" - consider removing`,
-            severity: config.rules['clean-code']['unused-imports'].severity as Severity
+            severity: (settings.severity as Severity) ?? 'info'
           });
         }
       }

package/principles/rules/solid/dip.ts

@@ -1,14 +1,22 @@
-import { Rule, Violation } from '../../types';
-import { getDefaultConfig } from '../../config';
+import { Rule, Violation, Severity } from '../../types';
+import { getActiveConfig } from '../../config';
 
-const config = getDefaultConfig();
-const { severity } = config.rules['solid']['dip'];
-const EXCLUDED_CLASSES = config.rules['solid']['dip'].exclude || [
+const DEFAULT_EXCLUDED_CLASSES = [
   'Date', 'Map', 'Set', 'Error', 'Array', 'Object', 'Promise'
 ];
 
+/**
+ * Read the excluded list from the ACTIVE config on each call.
+ *
+ * A module-load snapshot was #457: a project's `.principlesrc` override was
+ * parsed but never consulted.
+ */
+function excludedClasses(): (string | number)[] {
+  return getActiveConfig().rules['solid']['dip'].exclude ?? DEFAULT_EXCLUDED_CLASSES;
+}
+
 function shouldSkipInstantiation(className: string): boolean {
-  if (EXCLUDED_CLASSES.includes(className)) return true;
+  if (excludedClasses().includes(className)) return true;
   if (className.endsWith('Factory') || className.endsWith('Builder')) return true;
   return false;
 }
@@ -17,9 +25,11 @@ export const dipRule: Rule = {
   id: 'solid.dip',
   name: 'Dependency Inversion Principle Rule',
   threshold: 0,
-  severity: severity as 'error' | 'warning' | 'info',
+  severity: 'warning',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
     const violations: Violation[] = [];
+    const settings = getActiveConfig().rules['solid']['dip'];
+    const severity = (settings.severity as Severity) ?? 'warning';
 
     try {
       for (const cls_any of adapter.extractClasses() || []) {
@@ -36,7 +46,7 @@ export const dipRule: Rule = {
             file,
             line: cls.line || 0,
             ruleId: 'solid.dip',
-            severity: severity as 'error' | 'warning' | 'info',
+            severity,
             message: `Direct instantiation detected: new ${className}(). Prefer dependency injection for flexibility.`,
           });
         }

package/principles/rules/solid/isp.ts

@@ -1,32 +1,33 @@
 import { Rule, Violation } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const ispRule: Rule = {
   id: 'solid.isp',
   name: 'Interface Segregation Principle Rule',
-  threshold: config.rules['solid']['isp'].methodThreshold ?? 10,
-  severity: config.rules['solid']['isp'].severity as 'error' | 'warning' | 'info',
+  threshold: 10,
+  severity: 'info',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['solid']['isp'];
     
     try {
       const typedAdapter = adapter as { extractInterfaces?: () => Array<{name?: string; line?: number; methodCount?: number;}> | undefined };
       const interfaces = typedAdapter.extractInterfaces?.() || [];
+      const maxMethods = settings.methodThreshold ?? 10;
       
       for (const iface of interfaces) {
         const methodCount = iface.methodCount || 0;
         
-        if (methodCount > (config.rules['solid']['isp'].methodThreshold as number)) {
+        if (methodCount > maxMethods) {
           violations.push({
             file,
             line: iface.line ?? 1,
             ruleId: 'solid.isp',
             message: `Interface "${iface.name}" has too many methods: ${methodCount} (maximum: ${
-              config.rules['solid']['isp'].methodThreshold
+              maxMethods
             }). Consider splitting into focused interfaces.`,
-            severity: config.rules['solid']['isp'].severity as "error" | "warning" | "info"
+            severity: (settings.severity as "error" | "warning" | "info") ?? 'info'
           });
         }
       }

package/principles/rules/solid/lsp.ts

@@ -1,8 +1,6 @@
-import { Rule, Violation, Adapter } from '../../types';
-import { getDefaultConfig } from '../../config';
+import { Rule, Violation, Adapter, Severity } from '../../types';
+import { getActiveConfig } from '../../config';
 
-const config = getDefaultConfig();
-const severity = config.rules['solid']['lsp'].severity as 'error' | 'warning' | 'info';
 const PRIMITIVE_TYPES = new Set([
   'string', 'number', 'boolean', 'any', 'void', 'null', 'undefined', 'Object', 'Array',
 ]);
@@ -37,12 +35,14 @@ function collectMethodParamTypes(methodSignature: string): string[] {
 }
 
 function buildViolation(file: string, cls: ClassInfo, paramType: string): Violation {
+  // Read the ACTIVE severity here rather than at module load (#457).
+  const settings = getActiveConfig().rules['solid']['lsp'];
   return {
     file,
     line: cls.line ?? 0,
     ruleId: 'solid.lsp',
     message: `Possible LSP violation in "${cls.name}". Parameter type "${paramType}" may not be compatible with base class contract.`,
-    severity,
+    severity: (settings.severity as Severity) ?? 'info',
   };
 }
 
@@ -67,7 +67,7 @@ export const lspRule: Rule = {
   id: 'solid.lsp',
   name: 'Liskov Substitution Principle Rule',
   threshold: 0,
-  severity,
+  severity: 'info',
   check: (file: string, adapter: Adapter): Violation[] => {
     try {
       const classes = (adapter.extractClasses() || []) as ClassInfo[];

package/principles/rules/solid/ocp.ts

@@ -1,15 +1,16 @@
 import { Rule, Violation } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
+import { getActiveConfig } from '../../config';
 
 export const ocpRule: Rule = {
   id: 'solid.ocp',
   name: 'Open/Closed Principle Rule',
   threshold: 0,
-  severity: config.rules['solid']['ocp'].severity as "error" | "warning" | "info",
+  severity: 'info',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['solid']['ocp'];
+    const severity = (settings.severity as "error" | "warning" | "info") ?? 'info';
     
     try {
       const classes = adapter.extractClasses() || [];
@@ -28,7 +29,7 @@ export const ocpRule: Rule = {
               line: cls.line ?? 1,
               ruleId: 'solid.ocp',
               message: `Possible modification of base class "${baseClass}" while extending. Extension should not require modifying the base.`,
-              severity: config.rules['solid']['ocp'].severity as "error" | "warning" | "info"
+              severity: severity
             });
           }
         }

package/principles/rules/solid/srp.ts

@@ -1,21 +1,20 @@
 import { Rule, Violation } from '../../types';
-import { getDefaultConfig } from '../../config';
-
-const config = getDefaultConfig();
-const { methodThreshold, severity } = config.rules['solid']['srp'];
+import { getActiveConfig } from '../../config';
 
 export const srpRule: Rule = {
   id: 'solid.srp',
   name: 'Single Responsibility Principle Rule',
-  threshold: methodThreshold as number,
-  severity: severity as "error" | "warning" | "info",
+  threshold: 15,
+  severity: 'warning',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
     const violations: Violation[] = [];
+    // Read the ACTIVE config per invocation; a module-load snapshot was #457.
+    const settings = getActiveConfig().rules['solid']['srp'];
 
     try {
       const classes = adapter.extractClasses() || [];
-      const maxMethods = methodThreshold as number;
-      const sev = severity as "error" | "warning" | "info";
+      const maxMethods = settings.methodThreshold as number;
+      const sev = (settings.severity as 'error' | 'warning' | 'info') ?? 'warning';
 
       for (const raw of classes) {
         const cls = raw as { code?: string; line?: number; name?: string; methodCount?: number; imports?: Record<string, unknown> };

package/principles/types.ts

@@ -3,7 +3,22 @@ export type Severity = 'error' | 'warning' | 'info';
 export interface Rule {
   id: string;
   name: string;
+  /**
+   * The rule's BUILT-IN default threshold.
+   *
+   * @deprecated This is NOT necessarily the value being enforced. Since #457 the
+   * effective threshold comes from the active `.principlesrc` and is read inside
+   * `check()`. Reading this field to decide whether a violation should occur will
+   * disagree with the checker whenever the project overrides the threshold. Use
+   * `getActiveConfig().rules[group][rule].threshold` for the enforced value.
+   */
   threshold: number;
+  /**
+   * The rule's BUILT-IN default severity.
+   *
+   * @deprecated See {@link Rule.threshold}: the enforced severity comes from the
+   * active config. Individual `Violation.severity` values are authoritative.
+   */
   severity: Severity;
   check: (file: string, adapter: Adapter) => Violation[];
 }

package/scripts/__tests__/sync-package-content.test.js

@@ -588,3 +588,31 @@ describe('sync-package-content subprocess invocation', () => {
     expect(Object.keys(pkgJsonAfter.dependencies || {}).length).toBe(0, 'dependencies should remain empty');
   }, 10000);
 });
+
+/**
+ * @test REQ-TDD-005 load-time-no-sync
+ * @intent Requiring sync-package-content must not sync the repo — only executing it as a
+ *        script may. The top-level main() used to run on every require(), so a test that
+ *        merely imported checkDocsDrift regenerated the whole npm-package mirror mid-run
+ *        and tripped vitest-worktree-guard on CI (missing mirror of an uncommitted
+ *        canonical file was (re)created as a new untracked path).
+ * @covers AC-TDD-005-04
+ */
+describe('load-time behavior', () => {
+  it('require() performs no filesystem sync; main() runs only when executed directly', () => {
+    const modulePath = require.resolve('../sync-package-content');
+    delete require.cache[modulePath];
+    const copies = [];
+    const originalCopy = fs.copyFileSync;
+    fs.copyFileSync = (...args) => { copies.push(args); };
+    try {
+      require('../sync-package-content');
+    } finally {
+      fs.copyFileSync = originalCopy;
+    }
+    expect(copies, `require() must not copy; got ${copies.length} copies`).toHaveLength(0);
+    const mod = require.cache[modulePath].exports;
+    expect(typeof mod.checkDocsDrift).toBe('function');
+    expect(typeof mod.checkAdapterDrift).toBe('function');
+  });
+});