@archpilotlabs/archpilot 0.1.0 → 0.2.0

package/dist/archpilot-cli.js

@@ -214118,9 +214118,17 @@ async function pathExists3(targetPath) {
 async function countContractFiles(contractsDir) {
   try {
     const entries = await import_node_fs5.promises.readdir(contractsDir, { withFileTypes: true });
-    return entries.filter(
-      (entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".contract.json")
-    ).length;
+    let count = 0;
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(".contract.json")) {
+        count += 1;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        count += await countContractFiles(path5.join(contractsDir, entry.name));
+      }
+    }
+    return count;
   } catch {
     return 0;
   }
@@ -214135,7 +214143,29 @@ function countGovernedModulesFromConfig(value) {
     return modules.filter((entry) => typeof entry === "string" && entry.trim().length > 0).length;
   }
   if (modules && typeof modules === "object" && !Array.isArray(modules)) {
-    return Object.keys(modules).filter((key) => key.trim().length > 0).length;
+    const moduleCount = Object.keys(modules).filter((key) => key.trim().length > 0).length;
+    if (moduleCount > 0) {
+      return moduleCount;
+    }
+  }
+  const components = typed.components;
+  if (Array.isArray(components)) {
+    return components.filter((entry) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return false;
+      }
+      const component = entry;
+      return typeof component.id === "string" && component.id.trim().length > 0 && typeof component.path === "string" && component.path.trim().length > 0 && component.path.trim() !== ".";
+    }).length;
+  }
+  if (components && typeof components === "object" && !Array.isArray(components)) {
+    return Object.entries(components).filter(([key, value2]) => {
+      if (key.trim().length === 0 || !value2 || typeof value2 !== "object" || Array.isArray(value2)) {
+        return false;
+      }
+      const component = value2;
+      return typeof component.path === "string" && component.path.trim().length > 0 && component.path.trim() !== ".";
+    }).length;
   }
   return 0;
 }
@@ -214628,12 +214658,12 @@ function buildModelFromSnapshot(snapshot, generatedAtUtc, renderContext) {
     command: "archpilot bootstrap --with-contracts",
     inspectorActionId: "bootstrap-config-and-contracts",
     description: "Create missing setup config and contracts in one deterministic pass."
-  } : {
+  } : hasGovernedModules && hasMissingContracts ? {
     label: "Generate Contracts",
     command: "archpilot contracts generate",
     inspectorActionId: "generate-module-contracts",
     description: "Generate missing module contracts for discovered modules."
-  } : hasFailedFindings ? reviewFindingsAction : !snapshot.hasBaselineSnapshot ? createBaselineAction : snapshot.hasBaselineSnapshot && !snapshot.hasDriftReport ? runDriftCheckAction : missingAdrScaffolds ? generateAdrScaffoldsAction : missingGithubCiWorkflow ? {
+  } : runValidationAction : hasFailedFindings ? reviewFindingsAction : !snapshot.hasBaselineSnapshot ? createBaselineAction : snapshot.hasBaselineSnapshot && !snapshot.hasDriftReport ? runDriftCheckAction : missingAdrScaffolds ? generateAdrScaffoldsAction : missingGithubCiWorkflow ? {
     label: "Set up GitHub CI validation + upload",
     command: "ArchPilot: Setup GitHub CI Validation + Upload",
     inspectorActionId: "setup-github-ci-governance",
@@ -215263,6 +215293,35 @@ function isPeerModuleImport(dependencyImport) {
 function filterPeerModuleImports(imports) {
   return imports.filter(isPeerModuleImport);
 }
+function getComponentModuleRoots(workspaceRoot, architectureContract) {
+  const components = architectureContract?.components;
+  if (!components) {
+    return /* @__PURE__ */ new Map();
+  }
+  const rawEntries = Array.isArray(components) ? components.map((entry) => {
+    const typed = entry;
+    return [typed.id, entry];
+  }) : Object.entries(components);
+  const componentRoots = /* @__PURE__ */ new Map();
+  for (const [key, value] of rawEntries) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      continue;
+    }
+    const typed = value;
+    const componentId = typeof typed.id === "string" && typed.id.trim().length > 0 ? typed.id.trim() : typeof key === "string" && key.trim().length > 0 ? key.trim() : void 0;
+    const componentPath = typeof typed.path === "string" && typed.path.trim().length > 0 ? normalizePath3(typed.path.trim()) : void 0;
+    if (!componentId || !componentPath || componentPath === ".") {
+      continue;
+    }
+    componentRoots.set(
+      componentId,
+      path7.join(workspaceRoot, ...componentPath.split("/"))
+    );
+  }
+  return new Map(
+    [...componentRoots.entries()].sort(([left], [right]) => left.localeCompare(right))
+  );
+}
 function buildModuleHierarchyEdges(moduleIds) {
   const moduleIdSet = new Set(moduleIds);
   const edges = [];
@@ -215594,6 +215653,23 @@ async function findModuleRoots(workspaceRoot, modulesRootRelativePath = "src/mod
       [...moduleRoots.entries()].sort(([left], [right]) => left.localeCompare(right))
     );
   }
+  const componentModuleRoots = getComponentModuleRoots(workspaceRoot, architectureContract);
+  if (componentModuleRoots.size > 0) {
+    for (const [moduleName, moduleRoot] of componentModuleRoots.entries()) {
+      try {
+        const stats = await import_node_fs6.promises.stat(moduleRoot);
+        if (stats.isDirectory()) {
+          moduleRoots.set(moduleName, moduleRoot);
+        }
+      } catch {
+      }
+    }
+    if (moduleRoots.size > 0) {
+      return new Map(
+        [...moduleRoots.entries()].sort(([left], [right]) => left.localeCompare(right))
+      );
+    }
+  }
   for (const [moduleName, moduleRoot] of discoveredModuleRoots.entries()) {
     if (!moduleRoots.has(moduleName)) {
       moduleRoots.set(moduleName, moduleRoot);
@@ -215666,20 +215742,30 @@ function isTestSourcePath(relativePath) {
   }
   return /(^|\/)[^/]+\.(test|spec)\.[cm]?[jt]sx?$/u.test(normalized);
 }
-async function collectSourceFiles(directoryPath, adapter, scanRootPath = directoryPath) {
+async function collectSourceFiles(directoryPath, adapter, scanRootPath = directoryPath, excludedDirectoryRoots = []) {
   const entries = await import_node_fs6.promises.readdir(directoryPath, { withFileTypes: true });
   entries.sort((left, right) => left.name.localeCompare(right.name));
   const files = [];
   for (const entry of entries) {
     const fullPath = path7.join(directoryPath, entry.name);
     if (entry.isDirectory()) {
+      if (excludedDirectoryRoots.some(
+        (excludedRoot) => isPathInsideOrEqual2(fullPath, excludedRoot)
+      )) {
+        continue;
+      }
       const normalizedRelativeDirectory = normalizePath3(
         path7.relative(scanRootPath, fullPath)
       );
       if (adapter.ignoreDirectoryNames.includes(entry.name) || adapter.ignoreDirectoryNames.includes(normalizedRelativeDirectory)) {
         continue;
       }
-      files.push(...await collectSourceFiles(fullPath, adapter, scanRootPath));
+      files.push(...await collectSourceFiles(
+        fullPath,
+        adapter,
+        scanRootPath,
+        excludedDirectoryRoots
+      ));
       continue;
     }
     if (entry.isFile() && adapter.dependencyParsingFileExtensions.includes(
@@ -216331,8 +216417,11 @@ async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath,
     ([left], [right]) => left.localeCompare(right)
   )) {
     const childModuleRoots = [...moduleRoots.entries()].filter(([childModuleName, childModuleRoot]) => childModuleName !== moduleName && isPathInsideOrEqual2(childModuleRoot, moduleRoot)).map(([, childModuleRoot]) => childModuleRoot);
-    const sourceFiles = (await collectSourceFiles(moduleRoot, adapter)).filter(
-      (sourceFile) => !childModuleRoots.some((childModuleRoot) => isPathInsideOrEqual2(sourceFile, childModuleRoot))
+    const sourceFiles = await collectSourceFiles(
+      moduleRoot,
+      adapter,
+      moduleRoot,
+      childModuleRoots
     );
     for (const sourceFilePath of sourceFiles) {
       const sourceFileRelativePath = normalizePath3(
@@ -216558,6 +216647,16 @@ function validateComponentDependencyPolicies(architectureContract, imports) {
   }
   return findings;
 }
+function isModuleScopedDependencyImport(architectureContract, dependencyImport) {
+  if (!architectureContract) {
+    return true;
+  }
+  const dependencyMetadata = resolveImportDependencyContextMetadata(
+    architectureContract,
+    dependencyImport
+  );
+  return !dependencyMetadata.isExternal && dependencyMetadata.dependencyType !== "cross-component";
+}
 function buildDependencyConfigSkippedFindings(reason, options) {
   const findings = [];
   if (options.checkForbiddenDependencies) {
@@ -216861,8 +216960,12 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
     workspacePackageAliases,
     adapter
   );
+  options?.onCollectedImports?.(imports);
   const peerImports = filterPeerModuleImports(imports);
-  const actualBySource = buildActualImportedModuleSetBySource(peerImports, registeredModuleIds);
+  const moduleScopedPeerImports = peerImports.filter(
+    (dependencyImport) => isModuleScopedDependencyImport(architectureContract, dependencyImport)
+  );
+  const actualBySource = buildActualImportedModuleSetBySource(moduleScopedPeerImports, registeredModuleIds);
   const moduleContractCache = /* @__PURE__ */ new Map();
   const declaredBySource = /* @__PURE__ */ new Map();
   const hasContractByModule = /* @__PURE__ */ new Map();
@@ -216942,7 +217045,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     workspaceRoot,
     moduleRoots
   );
-  const imports = await collectCrossModuleImports(
+  const imports = options.precomputedImports ? [...options.precomputedImports] : await collectCrossModuleImports(
     workspaceRoot,
     modulesRoot,
     moduleRoots,
@@ -216951,12 +217054,15 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     adapter
   );
   const peerImports = filterPeerModuleImports(imports);
+  const moduleScopedPeerImports = peerImports.filter(
+    (dependencyImport) => isModuleScopedDependencyImport(architectureContract, dependencyImport)
+  );
   const findings = [];
   const moduleContractCache = /* @__PURE__ */ new Map();
   if (options.checkDeclaredDependencies) {
     const failuresByDependency = /* @__PURE__ */ new Map();
     const skippedFindings = /* @__PURE__ */ new Map();
-    for (const dependencyImport of peerImports) {
+    for (const dependencyImport of moduleScopedPeerImports) {
       const dependencyMetadata = resolveImportDependencyContextMetadata(
         architectureContract,
         dependencyImport
@@ -217063,7 +217169,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     });
     if (failures.length > 0) {
       findings.push(...failures);
-    } else if (peerImports.length === 0) {
+    } else if (moduleScopedPeerImports.length === 0) {
       findings.push({
         result: makeValidationResult(
           "AP-DEP-004",
@@ -217088,7 +217194,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
   if (options.checkPublicSurfaceImports) {
     const failures = [];
     const skippedFindings = /* @__PURE__ */ new Map();
-    for (const dependencyImport of peerImports) {
+    for (const dependencyImport of moduleScopedPeerImports) {
       const dependencyMetadata = resolveImportDependencyContextMetadata(
         architectureContract,
         dependencyImport
@@ -217212,7 +217318,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     }
     if (failures.length > 0) {
       findings.push(...failures);
-    } else if (peerImports.length === 0) {
+    } else if (moduleScopedPeerImports.length === 0) {
       findings.push({
         result: makeValidationResult(
           "AP-DEP-005",
@@ -217242,19 +217348,20 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
       architectureContract,
       { canonicalizeOverlappingPaths: true }
     );
-    const canonicalWorkspacePackageAliases = await buildWorkspacePackageAliasMap(
-      workspaceRoot,
-      canonicalModuleRoots
-    );
-    const canonicalImports = await collectCrossModuleImports(
+    const canonicalImports = options.precomputedImports ? [...options.precomputedImports] : await collectCrossModuleImports(
       workspaceRoot,
       modulesRoot,
       canonicalModuleRoots,
       explicitStandaloneModuleByPath,
-      canonicalWorkspacePackageAliases,
+      await buildWorkspacePackageAliasMap(
+        workspaceRoot,
+        canonicalModuleRoots
+      ),
       adapter
     );
-    const canonicalPeerImports = filterPeerModuleImports(canonicalImports);
+    const canonicalPeerImports = filterPeerModuleImports(canonicalImports).filter(
+      (dependencyImport) => isModuleScopedDependencyImport(architectureContract, dependencyImport)
+    );
     const registeredModuleIds = /* @__PURE__ */ new Set([
       ...canonicalModuleRoots.keys(),
       ...explicitStandaloneModuleByPath.values()
@@ -217340,7 +217447,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
     workspaceRoot,
     moduleRoots
   );
-  const imports = await collectCrossModuleImports(
+  const imports = options.precomputedImports ? [...options.precomputedImports] : await collectCrossModuleImports(
     workspaceRoot,
     modulesRootRelativePath,
     moduleRoots,
@@ -217349,6 +217456,9 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
     adapter
   );
   const peerImports = filterPeerModuleImports(imports);
+  const moduleScopedPeerImports = peerImports.filter(
+    (dependencyImport) => isModuleScopedDependencyImport(parsedArchitectureContract, dependencyImport)
+  );
   const findings = [];
   let dependencyRules;
   let dependencyRulesSkipReason;
@@ -217369,7 +217479,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
     }
   }
   if (options.checkCircularDependencies) {
-    const cycles = detectCircularDependencies([...moduleRoots.keys()], peerImports);
+    const cycles = detectCircularDependencies([...moduleRoots.keys()], moduleScopedPeerImports);
     if (cycles.length === 0) {
       findings.push({
         result: makeValidationResult(
@@ -217401,7 +217511,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
         })
       );
     } else {
-      const violations = peerImports.filter((dependencyImport) => {
+      const violations = moduleScopedPeerImports.filter((dependencyImport) => {
         if (parsedArchitectureContract) {
           const dependencyMetadata = resolveImportDependencyContextMetadata(
             parsedArchitectureContract,
@@ -217466,7 +217576,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
         })
       );
     } else {
-      const violations = peerImports.filter((dependencyImport) => {
+      const violations = moduleScopedPeerImports.filter((dependencyImport) => {
         if (parsedArchitectureContract) {
           const dependencyMetadata = resolveImportDependencyContextMetadata(
             parsedArchitectureContract,
@@ -218997,7 +219107,7 @@ function hasConfiguredModuleRegistryEntries(config) {
   return Object.keys(config.modules).length > 0;
 }
 function hasExplicitModuleRegistry(config) {
-  return Boolean(config && config.modules && typeof config.modules === "object" && !Array.isArray(config.modules));
+  return hasConfiguredModuleRegistryEntries(config);
 }
 function normalizePublicEntrypointList(entries) {
   return sortUnique3(entries.map((entry) => normalizePath6(entry.trim())).filter((entry) => entry.length > 0));
@@ -219225,6 +219335,59 @@ async function discoverModulesFromFallbackScan(workspaceRoot, modulesRoot = "src
   }
   return discovered;
 }
+function getComponentEntries(contract) {
+  const components = contract?.components;
+  if (!components) {
+    return [];
+  }
+  const rawEntries = Array.isArray(components) ? components.map((entry) => {
+    const typed = entry;
+    return [typed.id, entry];
+  }) : Object.entries(components);
+  const entries = [];
+  for (const [key, value] of rawEntries) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      continue;
+    }
+    const typed = value;
+    const componentId = typeof typed.id === "string" && typed.id.trim().length > 0 ? typed.id.trim() : typeof key === "string" && key.trim().length > 0 ? key.trim() : void 0;
+    const sourcePath = typeof typed.path === "string" && typed.path.trim().length > 0 ? normalizePath6(typed.path.trim()) : void 0;
+    if (!componentId || !sourcePath || sourcePath === ".") {
+      continue;
+    }
+    entries.push({ componentId, sourcePath });
+  }
+  return entries.sort((left, right) => left.componentId.localeCompare(right.componentId));
+}
+async function discoverModulesFromComponents(workspaceRoot, contract, contractsRoot = ".archpilot/contracts") {
+  const discovered = [];
+  for (const component of getComponentEntries(contract)) {
+    const absoluteSourcePath = path10.join(workspaceRoot, ...component.sourcePath.split("/"));
+    let sourcePathExists = false;
+    let sourceIsDirectory = false;
+    try {
+      const sourceStats = await import_node_fs7.promises.stat(absoluteSourcePath);
+      sourcePathExists = true;
+      sourceIsDirectory = sourceStats.isDirectory();
+    } catch {
+      sourcePathExists = false;
+    }
+    if (!sourceIsDirectory) {
+      continue;
+    }
+    const contractPath = `${contractsRoot}/${toSafeContractModuleFileStem2(component.componentId)}.contract.json`;
+    discovered.push({
+      moduleName: component.componentId,
+      sourcePath: component.sourcePath,
+      discoverySource: "inferred-scan",
+      sourcePathExists,
+      ...resolveModuleScopeForPath(workspaceRoot, component.sourcePath, contract) ? { scope: resolveModuleScopeForPath(workspaceRoot, component.sourcePath, contract) } : {},
+      contractPath,
+      contractExists: await pathExists7(path10.join(workspaceRoot, ...contractPath.split("/")))
+    });
+  }
+  return discovered;
+}
 function toArchitectureMapEdge(edge) {
   return {
     source: edge.sourceModule,
@@ -219319,7 +219482,11 @@ async function generateArchitectureMap(workspaceRoot, options) {
   );
   const modules = await measure(
     "architecture-map.discovery",
-    () => hasArchitectureJson && !shouldUseConfiguredRootInference && !shouldUseTopLevelWorkspaceInference ? discoverModulesFromArchitectureContract(workspaceRoot, contract, modulesRoot) : discoverModulesFromFallbackScan(
+    () => hasArchitectureJson && !shouldUseConfiguredRootInference && !shouldUseTopLevelWorkspaceInference ? discoverModulesFromArchitectureContract(workspaceRoot, contract, modulesRoot) : hasArchitectureJson && getComponentEntries(contract).length > 0 ? discoverModulesFromComponents(
+      workspaceRoot,
+      contract,
+      resolveContractsRootFromContract(contract)
+    ) : discoverModulesFromFallbackScan(
       workspaceRoot,
       modulesRoot,
       resolveContractsRootFromContract(contract),
@@ -222098,13 +222265,6 @@ var overallSetupGapWarningPenalty = 1;
 var overallSetupGapInfoPenalty = 1;
 var minScore = 0;
 var maxScore = 100;
-var singleBlockingErrorCap = 55;
-var twoBlockingErrorCap = 40;
-var severalBlockingErrorCap = 30;
-var manyBlockingErrorCap = 20;
-var criticalStructuralCap = 5;
-var architectureSmellWarningCategoryPenaltyCap = 7;
-var publicSurfaceBypassRuleIds = /* @__PURE__ */ new Set(["AP-DEP-005"]);
 var cycleRuleIds = /* @__PURE__ */ new Set(["AP-DEP-001", "AP-DEP-008"]);
 var severeDependencyRuleIds = /* @__PURE__ */ new Set([
   "AP-DEP-001",
@@ -222153,6 +222313,9 @@ var mediumWeightHeuristicRuleIds = /* @__PURE__ */ new Set([
   "AP-DOM-005",
   "AP-API-015"
 ]);
+var warningFamilyPenaltyCap = 18;
+var heuristicWarningFamilyPenaltyCap = 12;
+var architectureSmellFamilyPenaltyCap = 7;
 function clampScore(value) {
   if (value < minScore) {
     return minScore;
@@ -222162,6 +222325,204 @@ function clampScore(value) {
   }
   return value;
 }
+function getSeverityRank(severity) {
+  if (severity === "error") {
+    return 0;
+  }
+  if (severity === "warning") {
+    return 1;
+  }
+  return 2;
+}
+function getRuleFamily(ruleId) {
+  if (!ruleId) {
+    return "unknown";
+  }
+  const match = /^AP-[A-Z]+/u.exec(ruleId);
+  return match?.[0] ?? ruleId;
+}
+function extractProblemIdentity(deductionKey) {
+  if (!deductionKey) {
+    return "";
+  }
+  if (deductionKey.includes("|")) {
+    const parts2 = deductionKey.split("|");
+    if (parts2[0] === "quality" || parts2[0] === "setup" || parts2[0] === "guidance" || parts2[0] === "passed") {
+      parts2.shift();
+    }
+    if (parts2[0]?.startsWith("AP-")) {
+      parts2.shift();
+    }
+    return parts2.join("|");
+  }
+  const parts = deductionKey.split(":");
+  if (parts[0] === "quality" || parts[0] === "setup" || parts[0] === "guidance" || parts[0] === "passed") {
+    parts.shift();
+  }
+  if (parts[0]?.startsWith("AP-")) {
+    parts.shift();
+  }
+  return parts.join(":");
+}
+function normalizeProblemIdentity(result, identity) {
+  const normalized = identity.replace(/\\/g, "/").trim().toLowerCase();
+  if (!normalized) {
+    return "";
+  }
+  if (normalized.includes("|")) {
+    const parts = normalized.split("|");
+    if (result.category === "dependency" && parts.length >= 4 && /^\d+$/u.test(parts[3] ?? "")) {
+      return [parts[0], parts[1], parts[2], parts[4] ?? ""].join("|");
+    }
+  }
+  return normalized;
+}
+function buildQualityProblemClusterKey(result) {
+  const family = getRuleFamily(result.ruleId);
+  const identity = normalizeProblemIdentity(result, extractProblemIdentity(result.deductionKey));
+  if (typeof result.ruleId === "string" && cycleRuleIds.has(result.ruleId)) {
+    return ["quality", result.category, family, "cycle", identity || "shared-root-cause"].join("|");
+  }
+  if (result.severity === "warning") {
+    return ["quality", result.category, family, identity || result.ruleId || "generic"].join("|");
+  }
+  return ["quality", result.category, family, result.ruleId ?? "unknown", identity || "generic"].join("|");
+}
+function getClusterWeight(cluster, index) {
+  if (index === 0) {
+    return 1;
+  }
+  if (cluster.severity === "error") {
+    return Math.max(0.35, 0.85 - index * 0.15);
+  }
+  if (cluster.isArchitectureSmell) {
+    return Math.max(0.15, 0.65 - index * 0.12);
+  }
+  if (cluster.isHeuristic) {
+    return Math.max(0.2, 0.75 - index * 0.12);
+  }
+  return Math.max(0.2, 0.8 - index * 0.12);
+}
+function getFamilyPenaltyCap(cluster) {
+  if (cluster.severity !== "warning") {
+    return void 0;
+  }
+  if (cluster.isArchitectureSmell) {
+    return architectureSmellFamilyPenaltyCap;
+  }
+  if (cluster.isHeuristic) {
+    return heuristicWarningFamilyPenaltyCap;
+  }
+  return warningFamilyPenaltyCap;
+}
+function summarizeArchitectureScoreProblems(input2) {
+  const qualityResults = input2.results.filter(
+    (result) => !result.passed && (result.impact ?? "quality") === "quality"
+  );
+  const clusterMap = /* @__PURE__ */ new Map();
+  for (const result of qualityResults) {
+    const key = buildQualityProblemClusterKey(result);
+    const family = getRuleFamily(result.ruleId);
+    const existing = clusterMap.get(key);
+    const resultPenalty = getQualityPenaltyForResult(result);
+    if (existing) {
+      existing.resultCount += 1;
+      if (getSeverityRank(result.severity) < getSeverityRank(existing.severity)) {
+        existing.severity = result.severity;
+      }
+      existing.basePenalty = Math.max(existing.basePenalty, resultPenalty);
+      if (typeof result.ruleId === "string") {
+        existing.ruleIds.add(result.ruleId);
+      }
+      existing.isHeuristic = existing.isHeuristic || isHeuristicRuleId(result.ruleId);
+      existing.isArchitectureSmell = existing.isArchitectureSmell || isArchitectureSmellWarningRuleId(result.ruleId);
+      continue;
+    }
+    clusterMap.set(key, {
+      key,
+      category: result.category,
+      family,
+      severity: result.severity,
+      impact: result.impact ?? "quality",
+      ruleIds: new Set(typeof result.ruleId === "string" ? [result.ruleId] : []),
+      resultCount: 1,
+      basePenalty: resultPenalty,
+      isHeuristic: isHeuristicRuleId(result.ruleId),
+      isArchitectureSmell: isArchitectureSmellWarningRuleId(result.ruleId)
+    });
+  }
+  const familyGroups = /* @__PURE__ */ new Map();
+  const preliminaryClusters = [...clusterMap.values()].sort((left, right) => {
+    const severityCompare = getSeverityRank(left.severity) - getSeverityRank(right.severity);
+    if (severityCompare !== 0) {
+      return severityCompare;
+    }
+    const categoryCompare = left.category.localeCompare(right.category);
+    if (categoryCompare !== 0) {
+      return categoryCompare;
+    }
+    const familyCompare = left.family.localeCompare(right.family);
+    if (familyCompare !== 0) {
+      return familyCompare;
+    }
+    return left.key.localeCompare(right.key);
+  }).map((entry) => {
+    const confidenceBonus = Math.min(3, Math.max(0, entry.ruleIds.size - 1));
+    const duplicateBonus = Math.min(2, Math.max(0, Math.ceil(Math.log2(entry.resultCount)) - 1));
+    return {
+      key: entry.key,
+      category: entry.category,
+      family: entry.family,
+      severity: entry.severity,
+      impact: entry.impact,
+      ruleIds: [...entry.ruleIds].sort((left, right) => left.localeCompare(right)),
+      resultCount: entry.resultCount,
+      penalty: entry.basePenalty + confidenceBonus + duplicateBonus,
+      isHeuristic: entry.isHeuristic,
+      isArchitectureSmell: entry.isArchitectureSmell
+    };
+  });
+  for (const cluster of preliminaryClusters) {
+    const familyKey = `${cluster.category}|${cluster.family}`;
+    const existing = familyGroups.get(familyKey) ?? [];
+    existing.push(cluster);
+    familyGroups.set(familyKey, existing);
+  }
+  const clusters = [];
+  for (const group of [...familyGroups.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, value]) => value)) {
+    const ordered = [...group].sort((left, right) => {
+      const severityCompare = getSeverityRank(left.severity) - getSeverityRank(right.severity);
+      if (severityCompare !== 0) {
+        return severityCompare;
+      }
+      if (left.penalty !== right.penalty) {
+        return right.penalty - left.penalty;
+      }
+      return left.key.localeCompare(right.key);
+    });
+    let appliedPenalty = 0;
+    for (const [index, cluster] of ordered.entries()) {
+      const weightedPenalty = Math.round(cluster.penalty * getClusterWeight(cluster, index));
+      const familyCap = getFamilyPenaltyCap(cluster);
+      const remainingCap = familyCap === void 0 ? void 0 : Math.max(0, familyCap - appliedPenalty);
+      const finalPenalty = remainingCap === void 0 ? weightedPenalty : Math.min(weightedPenalty, remainingCap);
+      appliedPenalty += finalPenalty;
+      clusters.push({
+        ...cluster,
+        penalty: finalPenalty
+      });
+    }
+  }
+  const qualityClusterCount = clusters.length;
+  const blockingClusterCount = clusters.filter((cluster) => cluster.severity === "error").length;
+  const heuristicClusterCount = clusters.filter((cluster) => cluster.isHeuristic).length;
+  return {
+    clusters,
+    qualityClusterCount,
+    blockingClusterCount,
+    heuristicClusterCount
+  };
+}
 function getOverallSetupGapPenaltyForSeverity(severity) {
   if (severity === "error") {
     return overallSetupGapErrorPenalty;
@@ -222272,19 +222633,20 @@ function deriveGovernanceRiskLevelFromResults(results) {
 function applyFinalScoreAdjustments(input2) {
   let adjusted = input2.baseScore;
   const uniqueResults = dedupeResultsByDeductionKey(input2.results);
-  const publicSurfaceBypassViolations = uniqueResults.filter(
-    (result) => !result.passed && (result.impact ?? "quality") === "quality" && typeof result.ruleId === "string" && publicSurfaceBypassRuleIds.has(result.ruleId)
+  const problemSummary = summarizeArchitectureScoreProblems({ results: uniqueResults });
+  const publicSurfaceBypassViolations = problemSummary.clusters.filter(
+    (cluster) => cluster.ruleIds.includes("AP-DEP-005")
   ).length;
-  const cycleViolations = uniqueResults.filter(
-    (result) => !result.passed && (result.impact ?? "quality") === "quality" && typeof result.ruleId === "string" && cycleRuleIds.has(result.ruleId)
+  const cycleViolations = problemSummary.clusters.filter(
+    (cluster) => cluster.ruleIds.some((ruleId) => cycleRuleIds.has(ruleId))
   ).length;
   adjusted -= Math.min(6, publicSurfaceBypassViolations * 2);
   adjusted -= Math.min(4, cycleViolations * 2);
   const governanceRiskLevel = input2.context?.governanceRiskLevel ?? deriveGovernanceRiskLevelFromResults(input2.results);
   if (governanceRiskLevel === "critical") {
-    adjusted -= 6;
+    adjusted -= 4;
   } else if (governanceRiskLevel === "high") {
-    adjusted -= 3;
+    adjusted -= 2;
   }
   if (input2.context?.diffContextAvailable === false) {
     adjusted -= 1;
@@ -222293,7 +222655,7 @@ function applyFinalScoreAdjustments(input2) {
     adjusted = Math.min(adjusted, 85);
   }
   if (governanceRiskLevel === "critical") {
-    adjusted = Math.min(adjusted, 80);
+    adjusted = Math.min(adjusted, 82);
   }
   const apDep004OnlyFloor = getApDep004OnlyContractDriftFloor({
     categoryScores: input2.categoryScores,
@@ -222303,92 +222665,8 @@ function applyFinalScoreAdjustments(input2) {
     adjusted = Math.max(adjusted, apDep004OnlyFloor);
     return clampScore(Math.round(adjusted));
   }
-  const structuralCap = getBlockingStructuralScoreCap(uniqueResults);
-  if (structuralCap !== void 0) {
-    if (structuralCap.critical) {
-      adjusted = Math.min(adjusted, structuralCap.cap);
-    } else {
-      adjusted = Math.max(
-        adjusted,
-        Math.min(
-          structuralCap.cap,
-          getProportionalScoreForBlockingFailures({
-            categoryScores: input2.categoryScores,
-            results: uniqueResults,
-            blockingErrorCount: structuralCap.blockingErrorCount
-          })
-        )
-      );
-    }
-  }
   return clampScore(Math.round(adjusted));
 }
-function getBlockingStructuralScoreCap(results) {
-  const blockingQualityErrors = results.filter(
-    (result) => !result.passed && result.severity === "error" && (result.impact ?? "quality") === "quality"
-  );
-  if (blockingQualityErrors.length === 0) {
-    return void 0;
-  }
-  const ruleCounts = /* @__PURE__ */ new Map();
-  for (const result of blockingQualityErrors) {
-    if (typeof result.ruleId !== "string") {
-      continue;
-    }
-    ruleCounts.set(result.ruleId, (ruleCounts.get(result.ruleId) ?? 0) + 1);
-  }
-  const hasCriticalCycleCombination = (ruleCounts.get("AP-DEP-001") ?? 0) > 0 && (ruleCounts.get("AP-DEP-008") ?? 0) > 0;
-  const hasForbiddenNonPublicCombination = (ruleCounts.get("AP-DEP-002") ?? 0) > 0 && (ruleCounts.get("AP-DEP-003") ?? 0) > 0;
-  const hasRepeatedSevereStructuralRule = [...severeDependencyRuleIds].some(
-    (ruleId) => (ruleCounts.get(ruleId) ?? 0) >= 5
-  );
-  if (hasCriticalCycleCombination || hasForbiddenNonPublicCombination || hasRepeatedSevereStructuralRule) {
-    return {
-      cap: criticalStructuralCap,
-      blockingErrorCount: blockingQualityErrors.length,
-      critical: true
-    };
-  }
-  if (blockingQualityErrors.length === 1) {
-    return {
-      cap: singleBlockingErrorCap,
-      blockingErrorCount: blockingQualityErrors.length,
-      critical: false
-    };
-  }
-  if (blockingQualityErrors.length === 2) {
-    return {
-      cap: twoBlockingErrorCap,
-      blockingErrorCount: blockingQualityErrors.length,
-      critical: false
-    };
-  }
-  if (blockingQualityErrors.length <= 4) {
-    return {
-      cap: severalBlockingErrorCap,
-      blockingErrorCount: blockingQualityErrors.length,
-      critical: false
-    };
-  }
-  return {
-    cap: manyBlockingErrorCap,
-    blockingErrorCount: blockingQualityErrors.length,
-    critical: false
-  };
-}
-function getProportionalScoreForBlockingFailures(input2) {
-  const categoryScores = Object.values(input2.categoryScores ?? {});
-  if (categoryScores.length === 0) {
-    return 0;
-  }
-  const categoryAverage = categoryScores.reduce((total, score) => total + score, 0) / categoryScores.length;
-  const warningCount = input2.results.filter(
-    (result) => !result.passed && result.severity === "warning" && (result.impact ?? "quality") === "quality"
-  ).length;
-  const warningVolumePenalty = Math.min(35, warningCount * 0.45);
-  const blockingPenalty = 8 + Math.max(0, input2.blockingErrorCount - 1) * 8;
-  return clampScore(Math.round(categoryAverage - warningVolumePenalty - blockingPenalty));
-}
 function getApDep004OnlyContractDriftFloor(input2) {
   if (!input2.categoryScores) {
     return void 0;
@@ -222413,7 +222691,35 @@ function getApDep004OnlyContractDriftFloor(input2) {
   const categoryAverage = scores.reduce((total, score) => total + score, 0) / scores.length;
   return clampScore(Math.min(75, Math.max(65, Math.round(categoryAverage - 20))));
 }
+function calculateScopedScores(results, scopeKey, categories, context) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    const scopeId = result[scopeKey];
+    if (!scopeId) {
+      continue;
+    }
+    const existing = grouped.get(scopeId) ?? [];
+    existing.push(result);
+    grouped.set(scopeId, existing);
+  }
+  if (grouped.size === 0) {
+    return void 0;
+  }
+  return [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right)).reduce((accumulator, [scopeId, scopedResults]) => {
+    accumulator[scopeId] = calculateArchitectureHealthScore({
+      results: scopedResults,
+      categories,
+      context,
+      includeScopedScores: false
+    }).overallScore;
+    return accumulator;
+  }, {});
+}
 function calculateArchitectureHealthScore(input2) {
+  const applicableResults = input2.results.filter(
+    (result) => result.applicability !== "not-applicable"
+  );
+  const notApplicable = input2.results.length - applicableResults.length;
   const categoryOrder = input2.categories && input2.categories.length > 0 ? [...input2.categories] : [...defaultArchitectureHealthCategories];
   const categoryScoreMap = /* @__PURE__ */ new Map();
   for (const category of categoryOrder) {
@@ -222434,8 +222740,8 @@ function calculateArchitectureHealthScore(input2) {
   let readinessScore = 100;
   const appliedHealthDeductions = /* @__PURE__ */ new Set();
   const appliedReadinessDeductions = /* @__PURE__ */ new Set();
-  const architectureSmellWarningPenaltyByCategory = /* @__PURE__ */ new Map();
-  for (const result of input2.results) {
+  const qualityResults = [];
+  for (const result of applicableResults) {
     if (result.passed) {
       passed += 1;
       continue;
@@ -222465,21 +222771,7 @@ function calculateArchitectureHealthScore(input2) {
       readinessCategoryScoreMap.set(result.category, 100);
     }
     if (impact === "quality") {
-      const shouldApply = !healthDeductionKey || !appliedHealthDeductions.has(healthDeductionKey);
-      if (shouldApply) {
-        let penalty = getQualityPenaltyForResult(result);
-        if (result.severity === "warning" && isArchitectureSmellWarningRuleId(result.ruleId)) {
-          const applied = architectureSmellWarningPenaltyByCategory.get(result.category) ?? 0;
-          penalty = Math.min(penalty, Math.max(0, architectureSmellWarningCategoryPenaltyCap - applied));
-          architectureSmellWarningPenaltyByCategory.set(result.category, applied + penalty);
-        }
-        overallScore = clampScore(overallScore - penalty);
-        const categoryScore = categoryScoreMap.get(result.category) ?? 100;
-        categoryScoreMap.set(result.category, clampScore(categoryScore - penalty));
-        if (healthDeductionKey) {
-          appliedHealthDeductions.add(healthDeductionKey);
-        }
-      }
+      qualityResults.push(result);
     }
     if (impact === "setup-gap") {
       const shouldApplyOverall = !healthDeductionKey || !appliedHealthDeductions.has(healthDeductionKey);
@@ -222513,6 +222805,11 @@ function calculateArchitectureHealthScore(input2) {
       }
     }
   }
+  for (const cluster of summarizeArchitectureScoreProblems({ results: qualityResults }).clusters) {
+    overallScore = clampScore(overallScore - cluster.penalty);
+    const categoryScore = categoryScoreMap.get(cluster.category) ?? 100;
+    categoryScoreMap.set(cluster.category, clampScore(categoryScore - cluster.penalty));
+  }
   const categoryScores = [...categoryScoreMap.entries()].sort((left, right) => left[0].localeCompare(right[0])).reduce((accumulator, [category, score]) => {
     accumulator[category] = score;
     return accumulator;
@@ -222524,14 +222821,19 @@ function calculateArchitectureHealthScore(input2) {
   return {
     overallScore: applyFinalScoreAdjustments({
       baseScore: overallScore,
-      results: input2.results,
+      results: applicableResults,
       categoryScores,
       context: input2.context
     }),
     categoryScores,
+    ...input2.includeScopedScores === false ? {} : {
+      componentScores: calculateScopedScores(applicableResults, "componentId", input2.categories, input2.context),
+      moduleScores: calculateScopedScores(applicableResults, "moduleId", input2.categories, input2.context)
+    },
     readinessScore,
     readinessCategoryScores,
-    totalChecks: input2.results.length,
+    totalChecks: applicableResults.length,
+    notApplicable,
     errors,
     warnings,
     info,
@@ -228948,6 +229250,8 @@ var ValidationRuleCatalog = {
     title: "Modular monolith folder structure exists",
     category: "architecture",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether a modular monolith has a configured module root with clear top-level module or capability directories.",
     recommendedFix: "Set a valid module root in architecture.json and organize code into clear top-level module or capability folders under that root.",
     explanation: "This rule checks that architecture code is organized into explicit module or domain boundaries.",
@@ -228988,6 +229292,8 @@ src/
     title: "Module baseline files exist",
     category: "architecture",
     defaultSeverity: "warning",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Modules that expose public entrypoints or are depended on by other modules must provide an index.ts public entrypoint. Internal-only modules do not require index.ts.",
     recommendedFix: "Ensure each module has README.md. Add index.ts for modules with declared publicEntrypoints or inbound declared dependencies from other modules."
   },
@@ -228996,6 +229302,8 @@ src/
     title: "Module registry path exists",
     category: "architecture",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether each module path declared in architecture.json exists as a directory in the repository.",
     recommendedFix: "Update the module registry path in .archpilot/architecture.json or restore the missing module directory.",
     whyItMatters: "This is a setup/configuration mismatch: architecture.json points at a module path that is not present in the workspace, so validation cannot reliably connect the intended architecture to the current code.",
@@ -229014,6 +229322,8 @@ src/
     title: "Module contract file exists",
     category: "architecture",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether each module contract file referenced by the module registry exists on disk.",
     recommendedFix: "Generate or restore the missing module contract file, or update the module registry contract path in .archpilot/architecture.json.",
     whyItMatters: "This is a setup/configuration mismatch: architecture.json references a module contract file that is missing, so ArchPilot cannot validate declared dependencies, public entrypoints, or module ownership for that module.",
@@ -229030,6 +229340,8 @@ src/
     title: "Module contract identity matches registry",
     category: "architecture",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether each module contract JSON is valid, has a matching module identity, and uses valid array field shapes for core contract fields.",
     recommendedFix: "Fix module contract JSON syntax and ensure contract.module plus contract array fields are valid and aligned with the module registry."
   },
@@ -229038,6 +229350,8 @@ src/
     title: "Module public entrypoints are aligned",
     category: "architecture",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether module publicEntrypoints are consistent between architecture.json and each module contract file.",
     recommendedFix: "Align publicEntrypoints in .archpilot/architecture.json and the module contract file so both describe the same public surface."
   },
@@ -229152,6 +229466,8 @@ src/
     title: "Circular module dependency detected",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks for circular dependencies between modules under src/modules based on detected cross-module imports.",
     recommendedFix: "Break circular dependencies between modules by introducing a shared abstraction, moving common code, or reversing the dependency direction."
   },
@@ -229160,6 +229476,8 @@ src/
     title: "Forbidden cross-module dependency detected",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether cross-module imports violate the allowedDependencies declared in .archpilot/dependency-rules.json.",
     recommendedFix: "Update .archpilot/dependency-rules.json or refactor the import so the module depends only on explicitly allowed modules."
   },
@@ -229168,6 +229486,8 @@ src/
     title: "Non-public cross-module import detected",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether cross-module imports target another module through its public entrypoints rather than internal implementation files.",
     recommendedFix: "Import another module through src/modules/<module>/index.ts or src/modules/<module>/public rather than reaching into internal files."
   },
@@ -229176,6 +229496,8 @@ src/
     title: "Cross-module dependency missing from module contract",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether each cross-module import is declared in the source module contract dependsOn list.",
     recommendedFix: "Add the imported module to source-module contract dependsOn or remove the cross-module dependency.",
     explanation: "Cross-module imports must be declared in module contracts to keep architectural dependencies explicit.",
@@ -229193,6 +229515,8 @@ src/
     title: "Cross-module import bypasses public module surface",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether cross-module imports resolve only through target module public entrypoints declared in module contracts.",
     recommendedFix: "Import only through target module public entrypoints declared in its module contract.",
     explanation: "Cross-module imports should use only public entrypoints exposed by the target module contract.",
@@ -229207,6 +229531,8 @@ src/
     title: "Declared module dependency not used",
     category: "dependency",
     defaultSeverity: "warning",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether module contract dependsOn entries are actually used by cross-module imports from that module.",
     recommendedFix: "Remove unused modules from dependsOn or add a legitimate cross-module import that reflects the declared dependency.",
     whyItMatters: "The module contract declares an architectural dependency, but the current code does not use that dependency. That mismatch makes the contract less trustworthy for impact analysis, reviews, and dependency governance.",
@@ -229226,6 +229552,8 @@ import { reserveInventory } from "../inventory";`,
     title: "Potential orphan module detected",
     category: "dependency",
     defaultSeverity: "warning",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether a registered module has no peer-module dependencies and little evidence of intentional architectural use.",
     recommendedFix: "Add intentional-use evidence such as a contract, README, public entrypoint, package entrypoint, or remove the module if it is stale."
   },
@@ -229234,6 +229562,8 @@ import { reserveInventory } from "../inventory";`,
     title: "Transitive circular module dependency detected",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether declared and actual module dependencies form transitive dependency cycles with three or more modules.",
     recommendedFix: "Break the dependency chain so modules only depend on lower-level modules or shared services."
   },
@@ -229242,6 +229572,8 @@ import { reserveInventory } from "../inventory";`,
     title: "Module has high inbound dependency count",
     category: "dependency",
     defaultSeverity: "warning",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether a module has a high inbound dependency count, which may indicate an overloaded shared module or god module risk.",
     recommendedFix: "Review whether this module is becoming a shared bottleneck or god module. Consider splitting responsibilities or introducing clearer boundaries."
   },
@@ -229250,6 +229582,8 @@ import { reserveInventory } from "../inventory";`,
     title: "Dependency violates architecture layer direction",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Checks whether module dependencies violate configured architecture layer direction rules.",
     recommendedFix: "Generate .archpilot/layer-rules.json through ArchPilot initialization or add the file manually. Then refactor dependencies so modules depend only on modules in lower layers."
   },
@@ -229258,6 +229592,7 @@ import { reserveInventory } from "../inventory";`,
     title: "Cross-component dependency policy violation",
     category: "dependency",
     defaultSeverity: "error",
+    architectureScope: "component",
     description: "Checks whether cross-component imports violate allowedDependencies declared on source components in architecture.json.",
     recommendedFix: "Update the source component allowedDependencies list in .archpilot/architecture.json or refactor the import so the component depends only on explicitly allowed components.",
     whyItMatters: "Component dependency policies make workspace boundaries explicit so applications, services, and libraries do not drift into hidden coupling.",
@@ -229390,6 +229725,8 @@ import { reserveInventory } from "../inventory";`,
     title: "Cross-module direct database access bypasses module boundary",
     category: "database",
     defaultSeverity: "warning",
+    architectureScope: "module",
+    applicability: { requiresArchitectureModules: true },
     description: "Detects high-confidence references from one module to another module database artifact path (for example /<module>/db/ or /<module>/sql/).",
     recommendedFix: "Route cross-module data access through module contracts/public surfaces instead of direct database artifact references.",
     whyItMatters: "Direct cross-module DB access can bypass architecture boundaries and create hidden coupling.",
@@ -229782,6 +230119,54 @@ function getValidationRuleMetadataById(id) {
 function getAllValidationRuleMetadata() {
   return Object.keys(ValidationRuleCatalog).map((key) => ValidationRuleCatalog[key]).sort((a, b) => a.id.localeCompare(b.id));
 }
+function getConfiguredArchitectureModuleIds(contract) {
+  const moduleIds = new Set(Object.keys(contract.modules ?? {}));
+  const components = contract.components;
+  if (components && typeof components === "object") {
+    const entries = Array.isArray(components) ? components.map((component, index) => [component.id ?? `component-${index + 1}`, component]) : Object.entries(components);
+    for (const [componentId, component] of entries) {
+      if (!component || typeof component !== "object" || Array.isArray(component)) {
+        continue;
+      }
+      for (const moduleId of Object.keys(component.modules ?? {})) {
+        moduleIds.add(moduleId.includes("/") ? moduleId : `${componentId}/${moduleId}`);
+      }
+    }
+  }
+  return [...moduleIds].sort((left, right) => left.localeCompare(right));
+}
+function hasConfiguredArchitectureModules(contract) {
+  return getConfiguredArchitectureModuleIds(contract).length > 0;
+}
+function buildNotApplicableRuleResults(contract, validationConfig) {
+  const hasModules = hasConfiguredArchitectureModules(contract);
+  return getAllValidationRuleMetadata().filter((meta) => meta.applicability?.requiresArchitectureModules === true).filter((meta) => !isRuleDisabled(meta.id, validationConfig)).filter(() => !hasModules).map((meta) => ({
+    id: meta.id,
+    severity: meta.defaultSeverity,
+    passed: true,
+    applicability: "not-applicable",
+    applicabilityReason: "No architecture modules are configured at the project root or under components.",
+    message: `${meta.title} is not applicable because this architecture has no configured modules.`
+  }));
+}
+function applyRuleApplicability(results, contract, validationConfig, hasArchitectureModulesOverride) {
+  if (hasArchitectureModulesOverride ?? hasConfiguredArchitectureModules(contract)) {
+    return results.map((result) => ({
+      ...result,
+      applicability: result.applicability ?? "applicable"
+    }));
+  }
+  const moduleRequiredRuleIds = new Set(
+    getAllValidationRuleMetadata().filter((meta) => meta.applicability?.requiresArchitectureModules === true).map((meta) => meta.id)
+  );
+  return [
+    ...results.filter((result) => !moduleRequiredRuleIds.has(result.id)).map((result) => ({
+      ...result,
+      applicability: result.applicability ?? "applicable"
+    })),
+    ...buildNotApplicableRuleResults(contract, validationConfig)
+  ];
+}
 function getValidationSeverityPolicyNote() {
   return "ArchPilot uses enforcement-oriented severities by default: core architecture, API, dependency, and database safety violations are treated as errors; documentation gaps are warnings; advisory compatibility notices are informational.";
 }
@@ -229811,7 +230196,7 @@ function isHeuristicArchitectureSmellRuleId(ruleId) {
 }
 function buildArchitectureSmellSummaryFromResults(results) {
   const failedSmells = results.filter(
-    (result) => !result.passed && isHeuristicArchitectureSmellRuleId(result.id)
+    (result) => result.applicability !== "not-applicable" && !result.passed && isHeuristicArchitectureSmellRuleId(result.id)
   );
   const familyEntries = ["AP-APP", "AP-DOM", "AP-TXN"].map((family) => {
     const familyResults = failedSmells.filter((result) => result.id.startsWith(family));
@@ -229832,7 +230217,9 @@ function buildArchitectureSmellSummaryFromResults(results) {
   };
 }
 function buildFindingCountContext(results) {
-  const failedResults = results.filter((result) => !result.passed);
+  const failedResults = results.filter(
+    (result) => result.applicability !== "not-applicable" && !result.passed
+  );
   const normalizedKeys = /* @__PURE__ */ new Set();
   for (const result of failedResults) {
     normalizedKeys.add(classifyValidationResult(result).deductionKey);
@@ -229844,32 +230231,47 @@ function buildFindingCountContext(results) {
   };
 }
 function buildScoreExplanationSummary(results, score) {
+  const problemSummary = summarizeArchitectureScoreProblems({
+    results: results.map((result) => {
+      const classification = classifyValidationResult(result);
+      return {
+        ruleId: result.id,
+        category: getValidationRuleMetadataById(result.id).category,
+        severity: result.severity,
+        passed: result.passed,
+        applicability: result.applicability,
+        impact: classification.scoreImpact,
+        deductionKey: classification.deductionKey
+      };
+    })
+  });
   const categoryEntries = Object.entries(score.categoryScores).sort((left, right) => left[1] - right[1] || left[0].localeCompare(right[0])).slice(0, 3).map(([category, categoryScore]) => ({ category, score: categoryScore }));
-  const heuristicWarnings = results.filter(
+  const applicableResults = results.filter((result) => result.applicability !== "not-applicable");
+  const heuristicWarnings = applicableResults.filter(
     (result) => !result.passed && result.severity === "warning" && isHeuristicArchitectureSmellRuleId(result.id)
   ).length;
-  const dependencyWarnings = results.filter(
+  const dependencyWarnings = applicableResults.filter(
     (result) => !result.passed && result.severity === "warning" && result.id.startsWith("AP-DEP-")
   ).length;
-  const databaseWarnings = results.filter(
+  const databaseWarnings = applicableResults.filter(
     (result) => !result.passed && result.severity === "warning" && getValidationRuleMetadataById(result.id).category === "database"
   ).length;
-  const documentationWarnings = results.filter(
+  const documentationWarnings = applicableResults.filter(
     (result) => !result.passed && result.severity === "warning" && getValidationRuleMetadataById(result.id).category === "documentation"
   ).length;
-  const blockingDependencyErrors = results.filter(
-    (result) => !result.passed && result.severity === "error" && (result.id === "AP-DEP-001" || result.id === "AP-DEP-008")
+  const blockingDependencyErrors = problemSummary.clusters.filter(
+    (cluster) => cluster.severity === "error" && cluster.ruleIds.some((ruleId) => ruleId === "AP-DEP-001" || ruleId === "AP-DEP-008")
   ).length;
-  const whyScoreChanged = score.errors > 0 ? "Error-level findings carry the highest score impact." : heuristicWarnings > 0 && dependencyWarnings > 0 ? "The score reflects mostly modest architecture-smell warnings plus remaining dependency governance warnings." : heuristicWarnings > 0 ? "The score reflects modest cumulative impact from heuristic architecture-smell warnings." : dependencyWarnings > 0 ? "The score reflects dependency governance warning impact." : score.warnings > 0 ? "The score reflects warning-level findings with no errors." : "No active findings reduced the score.";
+  const whyScoreChanged = score.errors > 0 ? "Error-level findings carry the highest score impact, but repeated root-cause clusters are normalized before scoring." : heuristicWarnings > 0 && dependencyWarnings > 0 ? "The score reflects normalized warning clusters: capped architecture-review signals plus remaining dependency governance warnings." : heuristicWarnings > 0 ? "The score reflects capped cumulative impact from heuristic architecture-smell warning clusters." : dependencyWarnings > 0 ? "The score reflects dependency governance warning clusters after repeated-surface normalization." : score.warnings > 0 ? "The score reflects warning-level findings with volume normalization and diminishing returns for repeated problem families." : "No active findings reduced the score.";
   const largestScoreContributors = [];
   if (blockingDependencyErrors > 0) {
     largestScoreContributors.push(
-      "Circular dependency / blocking dependency violations have high score impact and can activate proportional scoring."
+      `Circular dependency / blocking dependency problems remain high-impact, but related findings are grouped into ${blockingDependencyErrors} blocking cluster${blockingDependencyErrors === 1 ? "" : "s"}.`
     );
   }
   if (databaseWarnings > 0) {
     largestScoreContributors.push(
-      `Database/query risk volume is a major contributor (${databaseWarnings} warning${databaseWarnings === 1 ? "" : "s"}; database score ${score.categoryScores.database ?? 100}/100).`
+      `Database/query risk volume is a major contributor (${databaseWarnings} warning${databaseWarnings === 1 ? "" : "s"} across ${problemSummary.clusters.filter((cluster) => cluster.category === "database").length} score cluster${problemSummary.clusters.filter((cluster) => cluster.category === "database").length === 1 ? "" : "s"}; database score ${score.categoryScores.database ?? 100}/100).`
     );
   }
   if (documentationWarnings > 0) {
@@ -229879,12 +230281,12 @@ function buildScoreExplanationSummary(results, score) {
   }
   if (heuristicWarnings > 0) {
     largestScoreContributors.push(
-      `Heuristic AP-APP/AP-DOM/AP-TXN findings are capped and did not dominate the score (${heuristicWarnings} warning${heuristicWarnings === 1 ? "" : "s"}).`
+      `Heuristic AP-APP/AP-DOM/AP-TXN findings are capped and did not dominate the score (${heuristicWarnings} warning${heuristicWarnings === 1 ? "" : "s"} across ${problemSummary.heuristicClusterCount} heuristic cluster${problemSummary.heuristicClusterCount === 1 ? "" : "s"}).`
     );
   }
   if (score.warnings > 1) {
     largestScoreContributors.push(
-      "Fixing one warning may not visibly move the rounded score; grouped fixes such as dependency cycles or repeated DQR findings usually move it more."
+      `Fixing one warning may not visibly move the rounded score; grouped fixes that clear repeated problem clusters (${problemSummary.qualityClusterCount} quality cluster${problemSummary.qualityClusterCount === 1 ? "" : "s"}) usually move it more.`
     );
   }
   return {
@@ -229954,6 +230356,13 @@ function buildDependencyDeductionKey(result) {
   ].join("|");
 }
 function classifyValidationResult(result) {
+  if (result.applicability === "not-applicable") {
+    return {
+      kind: "guidance",
+      scoreImpact: "guidance",
+      deductionKey: `not-applicable:${result.id}`
+    };
+  }
   if (result.passed) {
     return {
       kind: "guidance",
@@ -230059,6 +230468,9 @@ function buildValidationStatusSummary(results, disabledCount = 0, suppressedCoun
         category: getValidationRuleMetadataById(result.id).category,
         severity: result.severity,
         passed: result.passed,
+        applicability: result.applicability,
+        ...result.sourceComponentId ? { componentId: result.sourceComponentId } : {},
+        ...result.module ? { moduleId: result.module } : {},
         impact: classification.scoreImpact,
         deductionKey: classification.deductionKey
       };
@@ -230074,6 +230486,7 @@ function buildValidationStatusSummary(results, disabledCount = 0, suppressedCoun
   const scoreExplanation = buildScoreExplanationSummary(results, score);
   const base = {
     totalRulesEvaluated,
+    notApplicable: score.notApplicable,
     disabled: disabledCount,
     passed,
     failed,
@@ -230089,6 +230502,8 @@ function buildValidationStatusSummary(results, disabledCount = 0, suppressedCoun
     info,
     healthScore: score.overallScore,
     categoryScores: score.categoryScores,
+    ...score.componentScores ? { componentScores: score.componentScores } : {},
+    ...score.moduleScores ? { moduleScores: score.moduleScores } : {},
     readinessScore: score.readinessScore,
     readinessCategoryScores: score.readinessCategoryScores,
     setupGaps: score.setupGaps,
@@ -230386,6 +230801,8 @@ function buildValidationStatusExport(config, results, validationConfig, suppress
       category: meta.category,
       severity: r.severity,
       passed: r.passed,
+      ...r.applicability ? { applicability: r.applicability } : {},
+      ...r.applicabilityReason ? { applicabilityReason: r.applicabilityReason } : {},
       message: r.message,
       kind: classification.kind,
       ...r.findingType ? { findingType: r.findingType } : {},
@@ -230403,7 +230820,14 @@ function buildValidationStatusExport(config, results, validationConfig, suppress
       ...r.exceptionTarget ? { exceptionTarget: r.exceptionTarget } : {},
       ...r.sourceFile ? { sourceFile: r.sourceFile } : {},
       ...r.sourceLine !== void 0 ? { sourceLine: r.sourceLine } : {},
-      ...r.sourceColumn !== void 0 ? { sourceColumn: r.sourceColumn } : {}
+      ...r.sourceColumn !== void 0 ? { sourceColumn: r.sourceColumn } : {},
+      ...r.dependencyType ? { dependencyType: r.dependencyType } : {},
+      ...r.sourceComponentId ? { sourceComponentId: r.sourceComponentId } : {},
+      ...r.sourceComponentName ? { sourceComponentName: r.sourceComponentName } : {},
+      ...r.targetComponentId !== void 0 ? { targetComponentId: r.targetComponentId } : {},
+      ...r.targetComponentName !== void 0 ? { targetComponentName: r.targetComponentName } : {},
+      ...r.resolvedTargetPath !== void 0 ? { resolvedTargetPath: r.resolvedTargetPath } : {},
+      ...r.isExternal !== void 0 ? { isExternal: r.isExternal } : {}
     };
   });
   return {
@@ -231000,37 +231424,38 @@ function dedupeDependencyFindings(findings) {
   }
   return deduped;
 }
-async function validateModuleDependencies(workspaceRoot, contract, validationConfig, onDependencyConfigError, dependencyRulesConfigOverride) {
+async function validateModuleDependencies(workspaceRoot, contract, validationConfig, onDependencyConfigError, dependencyRulesConfigOverride, precomputedImports, hasArchitectureModulesOverride) {
   const modulesRootRelativePath = await getConfiguredModulesRoot(workspaceRoot, contract);
+  const hasArchitectureModules = hasArchitectureModulesOverride ?? hasConfiguredArchitectureModules(contract);
   const dependencyRuleChecks = {
     modulesRootRelativePath,
-    checkCircularDependencies: !isRuleDisabled(
+    checkCircularDependencies: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_CIRCULAR_MODULE_DEPENDENCY,
       validationConfig
     ),
-    checkForbiddenDependencies: !isRuleDisabled(
+    checkForbiddenDependencies: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_FORBIDDEN_CROSS_MODULE_DEPENDENCY,
       validationConfig
     ),
-    checkNonPublicImports: !isRuleDisabled(
+    checkNonPublicImports: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_NON_PUBLIC_CROSS_MODULE_IMPORT,
       validationConfig
     ),
     checkComponentDependencyPolicies: !isRuleDisabled(
-      ValidationRuleIds.DEP_LAYER_DIRECTION_VIOLATION,
+      ValidationRuleIds.DEP_CROSS_COMPONENT_POLICY_VIOLATION,
       validationConfig
     )
   };
   const contractDependencyRuleChecks = {
-    checkDeclaredDependencies: !isRuleDisabled(
+    checkDeclaredDependencies: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_CROSS_MODULE_DEPENDENCY_DECLARED_IN_CONTRACT,
       validationConfig
     ),
-    checkPublicSurfaceImports: !isRuleDisabled(
+    checkPublicSurfaceImports: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_CROSS_MODULE_IMPORT_USES_PUBLIC_SURFACE_ONLY,
       validationConfig
     ),
-    checkDeclaredDependenciesUsedByCode: !isRuleDisabled(
+    checkDeclaredDependenciesUsedByCode: hasArchitectureModules && !isRuleDisabled(
       ValidationRuleIds.DEP_DECLARED_MODULE_DEPENDENCY_NOT_USED,
       validationConfig
     )
@@ -231039,12 +231464,14 @@ async function validateModuleDependencies(workspaceRoot, contract, validationCon
     const [legacyFindings, contractFindings] = await Promise.all([
       validateDependencyBoundaries(workspaceRoot, {
         ...dependencyRuleChecks,
-        ...dependencyRulesConfigOverride ? { dependencyRulesConfigOverride } : {}
+        ...dependencyRulesConfigOverride ? { dependencyRulesConfigOverride } : {},
+        ...precomputedImports ? { precomputedImports } : {}
       }),
       validateDependencyContractBoundaries(workspaceRoot, contract, {
         ...contractDependencyRuleChecks,
         modulesRootRelativePath,
-        suppressPublicSurfaceFailuresForNonPublicImports: dependencyRuleChecks.checkNonPublicImports
+        suppressPublicSurfaceFailuresForNonPublicImports: dependencyRuleChecks.checkNonPublicImports,
+        ...precomputedImports ? { precomputedImports } : {}
       })
     ]);
     const findings = dedupeDependencyFindings([...legacyFindings, ...contractFindings]);
@@ -232365,6 +232792,7 @@ async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
     "Loading suppressions",
     () => readValidationSuppressions(workspaceRoot, knownRuleIds)
   );
+  let hasArchitectureModules = hasConfiguredArchitectureModules(architectureContract);
   const results = [];
   results.push(...validationConfigLoad.configResults);
   if (projectConfigLoad.invalidJson) {
@@ -232384,6 +232812,32 @@ async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
     });
   }
   results.push(...suppressionsConfig.configResults);
+  const configuredModulesRoot = await phase(
+    "Discovering project modules",
+    () => getConfiguredModulesRoot(
+      workspaceRoot,
+      architectureContract
+    )
+  );
+  let precomputedDependencyImports;
+  const dependencyGraphSummary = await phase(
+    "Building dependency graph",
+    () => buildDependencyGraphSummary(workspaceRoot, architectureContract, {
+      modulesRootRelativePath: configuredModulesRoot,
+      onCollectedImports: (imports) => {
+        precomputedDependencyImports = imports;
+      }
+    })
+  );
+  hasArchitectureModules = hasArchitectureModules || dependencyGraphSummary.modules.length > 0;
+  emitOperationalMessage(
+    options?.onOperationalMessage,
+    "info",
+    `Dependency scan summary: modules=${dependencyGraphSummary.modules.length}, importEdges=${dependencyGraphSummary.modules.reduce(
+      (total, moduleEntry) => total + moduleEntry.actualDependencies.length,
+      0
+    )}, ignoredDefaults=node_modules,.git,.archpilot,dist,build,out,coverage,fixtures.`
+  );
   const ruleExecutionResults = await phase(
     "Executing validation rules",
     () => Promise.all([
@@ -232397,11 +232851,11 @@ async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
       ),
       profileValidationPhase(
         "module contract registry analyzer",
-        () => validateModuleContractRegistryIntegrity(
+        () => hasArchitectureModules ? validateModuleContractRegistryIntegrity(
           workspaceRoot,
           architectureContract,
           validationConfig
-        )
+        ) : Promise.resolve([])
       ),
       profileValidationPhase(
         "module dependency analyzer",
@@ -232410,7 +232864,9 @@ async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
           architectureContract,
           validationConfig,
           options?.onDependencyConfigError,
-          projectConfigLoad.config?.policySource ? effectivePolicy.effectiveDependencyRulesConfig : void 0
+          projectConfigLoad.config?.policySource ? effectivePolicy.effectiveDependencyRulesConfig : void 0,
+          precomputedDependencyImports,
+          hasArchitectureModules
         )
       ),
       profileValidationPhase(
@@ -232494,54 +232950,41 @@ async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
     ])
   );
   results.push(...ruleExecutionResults.flat(), ...adrValidation.results);
-  const configuredModulesRoot = await phase(
-    "Discovering project modules",
-    () => getConfiguredModulesRoot(
-      workspaceRoot,
-      architectureContract
-    )
-  );
-  const dependencyGraphSummary = await phase(
-    "Building dependency graph",
-    () => buildDependencyGraphSummary(workspaceRoot, architectureContract, {
-      modulesRootRelativePath: configuredModulesRoot
-    })
-  );
-  emitOperationalMessage(
-    options?.onOperationalMessage,
-    "info",
-    `Dependency scan summary: modules=${dependencyGraphSummary.modules.length}, importEdges=${dependencyGraphSummary.modules.reduce(
-      (total, moduleEntry) => total + moduleEntry.actualDependencies.length,
-      0
-    )}, ignoredDefaults=node_modules,.git,.archpilot,dist,build,out,coverage,fixtures.`
-  );
-  results.push(
-    ...await phase(
-      "Analyzing dependency graph rules",
-      () => validateDependencyLayerDirection(
+  if (hasArchitectureModules) {
+    results.push(
+      ...await phase(
+        "Analyzing dependency graph rules",
+        () => validateDependencyLayerDirection(
+          workspaceRoot,
+          dependencyGraphSummary,
+          validationConfig
+        )
+      ),
+      ...validateTransitiveModuleDependencyCycles(
+        dependencyGraphSummary,
+        validationConfig
+      ),
+      ...validateHighInboundDependencyCount(
+        architectureContract,
+        dependencyGraphSummary,
+        validationConfig
+      ),
+      ...await validateDependencyGraphIsolation(
         workspaceRoot,
+        architectureContract,
         dependencyGraphSummary,
         validationConfig
       )
-    ),
-    ...validateTransitiveModuleDependencyCycles(
-      dependencyGraphSummary,
-      validationConfig
-    ),
-    ...validateHighInboundDependencyCount(
-      architectureContract,
-      dependencyGraphSummary,
-      validationConfig
-    ),
-    ...await validateDependencyGraphIsolation(
-      workspaceRoot,
-      architectureContract,
-      dependencyGraphSummary,
-      validationConfig
-    )
-  );
+    );
+  }
   const scopeModules = options?.moduleScope ? [...new Set(options.moduleScope)].sort((left, right) => left.localeCompare(right)) : [];
-  const effectiveResults = applyEffectiveSeverities(results, validationConfig.config);
+  const applicableResults = applyRuleApplicability(
+    results,
+    architectureContract,
+    validationConfig,
+    hasArchitectureModules
+  );
+  const effectiveResults = applyEffectiveSeverities(applicableResults, validationConfig.config);
   const scopedResults = filterResultsByModuleScope(effectiveResults, scopeModules);
   const scopedResultsWithQuickFix = attachQuickFixMetadataToResults(scopedResults);
   const scopedDependencyGraphSummary = filterDependencyGraphSummaryByModuleScope(
@@ -232958,7 +233401,7 @@ function buildDefaultImpactAnalysisFromSignals(input2) {
     }
   };
 }
-function getSeverityRank(severity) {
+function getSeverityRank2(severity) {
   switch (severity) {
     case "error":
       return 1;
@@ -233139,7 +233582,7 @@ function groupReviewFindingsByRule(findings) {
   return [...groups.values()];
 }
 function compareReviewFinding(left, right) {
-  const severityCompare = getSeverityRank(left.severity) - getSeverityRank(right.severity);
+  const severityCompare = getSeverityRank2(left.severity) - getSeverityRank2(right.severity);
   if (severityCompare !== 0) {
     return severityCompare;
   }
@@ -233160,7 +233603,7 @@ function compareReviewFinding(left, right) {
   return left.message.localeCompare(right.message);
 }
 function compareSuppressedFinding(left, right) {
-  const severityCompare = getSeverityRank(left.severity) - getSeverityRank(right.severity);
+  const severityCompare = getSeverityRank2(left.severity) - getSeverityRank2(right.severity);
   if (severityCompare !== 0) {
     return severityCompare;
   }
@@ -233476,6 +233919,19 @@ function buildArchitectureSmellSummary(findings) {
   };
 }
 function buildScoreExplanation(results, healthScore) {
+  const problemSummary = summarizeArchitectureScoreProblems({
+    results: results.map((result) => {
+      const classification = classifyValidationResult(result);
+      return {
+        ruleId: result.id,
+        category: getValidationRuleMetadataById(result.id).category,
+        severity: result.severity,
+        passed: result.passed,
+        impact: classification.scoreImpact,
+        deductionKey: classification.deductionKey
+      };
+    })
+  });
   const heuristicWarnings = results.filter(
     (result) => !result.passed && result.severity === "warning" && isHeuristicArchitectureSmellRuleId2(result.id)
   ).length;
@@ -233488,20 +233944,21 @@ function buildScoreExplanation(results, healthScore) {
   const documentationWarnings = results.filter(
     (result) => !result.passed && result.severity === "warning" && getValidationRuleMetadataById(result.id).category === "documentation"
   ).length;
-  const blockingDependencyErrors = results.filter(
-    (result) => !result.passed && result.severity === "error" && (result.id === "AP-DEP-001" || result.id === "AP-DEP-008")
+  const blockingDependencyErrors = problemSummary.clusters.filter(
+    (cluster) => cluster.severity === "error" && cluster.ruleIds.some((ruleId) => ruleId === "AP-DEP-001" || ruleId === "AP-DEP-008")
   ).length;
   const highestImpactCategories = Object.entries(healthScore.categoryScores).sort((left, right) => left[1] - right[1] || left[0].localeCompare(right[0])).slice(0, 3).map(([category, score]) => ({ category, score }));
-  const whyScoreChanged = healthScore.errors > 0 ? "Error-level findings carry the highest score impact." : heuristicWarnings > 0 && dependencyWarnings > 0 ? "The score reflects mostly modest architecture-smell warnings plus remaining dependency governance warnings." : heuristicWarnings > 0 ? "The score reflects modest cumulative impact from heuristic architecture-smell warnings." : dependencyWarnings > 0 ? "The score reflects dependency governance warning impact." : healthScore.warnings > 0 ? "The score reflects warning-level findings with no errors." : "No active findings reduced the score.";
+  const whyScoreChanged = healthScore.errors > 0 ? "Error-level findings carry the highest score impact, but repeated root-cause clusters are normalized before scoring." : heuristicWarnings > 0 && dependencyWarnings > 0 ? "The score reflects normalized warning clusters: capped architecture-review signals plus remaining dependency governance warnings." : heuristicWarnings > 0 ? "The score reflects capped cumulative impact from heuristic architecture-smell warning clusters." : dependencyWarnings > 0 ? "The score reflects dependency governance warning clusters after repeated-surface normalization." : healthScore.warnings > 0 ? "The score reflects warning-level findings with volume normalization and diminishing returns for repeated problem families." : "No active findings reduced the score.";
   const largestScoreContributors = [];
   if (blockingDependencyErrors > 0) {
     largestScoreContributors.push(
-      "Circular dependency / blocking dependency violations have high score impact and can activate proportional scoring."
+      `Circular dependency / blocking dependency problems remain high-impact, but related findings are grouped into ${blockingDependencyErrors} blocking cluster${blockingDependencyErrors === 1 ? "" : "s"}.`
     );
   }
   if (databaseWarnings > 0) {
+    const databaseClusters = problemSummary.clusters.filter((cluster) => cluster.category === "database").length;
     largestScoreContributors.push(
-      `Database/query risk volume is a major contributor (${databaseWarnings} warning${databaseWarnings === 1 ? "" : "s"}; database score ${healthScore.categoryScores.database ?? 100}/100).`
+      `Database/query risk volume is a major contributor (${databaseWarnings} warning${databaseWarnings === 1 ? "" : "s"} across ${databaseClusters} score cluster${databaseClusters === 1 ? "" : "s"}; database score ${healthScore.categoryScores.database ?? 100}/100).`
     );
   }
   if (documentationWarnings > 0) {
@@ -233511,12 +233968,12 @@ function buildScoreExplanation(results, healthScore) {
   }
   if (heuristicWarnings > 0) {
     largestScoreContributors.push(
-      `Heuristic AP-APP/AP-DOM/AP-TXN findings are capped and did not dominate the score (${heuristicWarnings} warning${heuristicWarnings === 1 ? "" : "s"}).`
+      `Heuristic AP-APP/AP-DOM/AP-TXN findings are capped and did not dominate the score (${heuristicWarnings} warning${heuristicWarnings === 1 ? "" : "s"} across ${problemSummary.heuristicClusterCount} heuristic cluster${problemSummary.heuristicClusterCount === 1 ? "" : "s"}).`
     );
   }
   if (healthScore.warnings > 1) {
     largestScoreContributors.push(
-      "Fixing one warning may not visibly move the rounded score; grouped fixes such as dependency cycles or repeated DQR findings usually move it more."
+      `Fixing one warning may not visibly move the rounded score; grouped fixes that clear repeated problem clusters (${problemSummary.qualityClusterCount} quality cluster${problemSummary.qualityClusterCount === 1 ? "" : "s"}) usually move it more.`
     );
   }
   return {