@archpilotlabs/archpilot 0.0.9 → 0.0.11

package/dist/archpilot-cli.js

@@ -213475,7 +213475,264 @@ async function listModuleDirectoryNames(workspaceRoot, modulesRootRelativePath =
   const entries = await import_node_fs.promises.readdir(modulesRoot, { withFileTypes: true });
   return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
 }
+var ignoredModuleDirectoryNames = /* @__PURE__ */ new Set([
+  ".git",
+  ".archpilot",
+  ".vscode",
+  ".vscode-test",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  "generated",
+  "target",
+  "vendor",
+  ".venv",
+  "venv",
+  "__pycache__"
+]);
+var noisyModuleDirectoryNames = /* @__PURE__ */ new Set([
+  "components",
+  "hooks",
+  "utils",
+  "util",
+  "lib",
+  "common",
+  "shared",
+  "shared-ui",
+  "types",
+  "constants",
+  "config",
+  "test",
+  "tests",
+  "__tests__",
+  "fixtures",
+  "mocks",
+  "__mocks__",
+  "generated",
+  "dist",
+  "build",
+  "out",
+  "node_modules"
+]);
+var sourceFileExtensions = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".vue",
+  ".java",
+  ".py",
+  ".php",
+  ".go",
+  ".cs",
+  ".rb",
+  ".kt",
+  ".swift",
+  ".rs"
+]);
+var publicEntrypointNames = /* @__PURE__ */ new Set([
+  "index.ts",
+  "index.tsx",
+  "index.js",
+  "index.jsx",
+  "index.vue",
+  "__init__.py",
+  "main.go",
+  "mod.ts",
+  "mod.js"
+]);
+function isIgnoredDirectoryName(directoryName) {
+  return ignoredModuleDirectoryNames.has(directoryName.toLowerCase());
+}
+function isNoisyModuleName(moduleName) {
+  return noisyModuleDirectoryNames.has(moduleName.toLowerCase());
+}
+function toPathSegments(relativePath) {
+  return normalizePath(relativePath).split("/").filter((segment) => segment.length > 0);
+}
+function toModuleIdFromPath(relativePath, fallbackRoot) {
+  const segments = toPathSegments(relativePath);
+  const lowerSegments = segments.map((segment) => segment.toLowerCase());
+  const sourceIndex = lowerSegments.lastIndexOf("src");
+  if (sourceIndex >= 0 && sourceIndex + 2 < segments.length) {
+    const parent = segments[sourceIndex - 1];
+    const container = lowerSegments[sourceIndex + 1];
+    if (["modules", "features"].includes(container)) {
+      return [parent, segments[sourceIndex + 2]].filter(Boolean).join("/");
+    }
+    if (["domain", "domains", "application", "infrastructure"].includes(container)) {
+      return [segments[sourceIndex + 1], segments[sourceIndex + 2]].join("/");
+    }
+    return [parent, segments[sourceIndex + 1]].filter(Boolean).join("/");
+  }
+  if (sourceIndex >= 0 && sourceIndex + 1 < segments.length) {
+    const parent = segments[sourceIndex - 1];
+    return [parent, segments[sourceIndex + 1]].filter(Boolean).join("/");
+  }
+  if (segments[0] === "src" && segments.length >= 3) {
+    return `${segments[1]}/${segments[2]}`;
+  }
+  if (fallbackRoot) {
+    const rootSegments = toPathSegments(fallbackRoot);
+    const relativeSegments = segments.slice(rootSegments.length);
+    if (relativeSegments.length > 0) {
+      return relativeSegments.join("/");
+    }
+  }
+  return segments.slice(-1)[0] ?? relativePath;
+}
+function isKnownNestedModuleRoot(relativePath) {
+  const segments = toPathSegments(relativePath).map((segment) => segment.toLowerCase());
+  if (segments.length < 2) {
+    return false;
+  }
+  const lastParent = segments[segments.length - 2];
+  if (["modules", "features", "domain", "domains", "application", "infrastructure"].includes(lastParent)) {
+    return true;
+  }
+  if (segments.length >= 3 && segments[segments.length - 3] === "src") {
+    return true;
+  }
+  return false;
+}
+async function inspectPotentialModuleRoot(absolutePath) {
+  let sourceFileCount = 0;
+  let hasPublicEntrypoint = false;
+  const queue = [{ absolutePath, depth: 0 }];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = await import_node_fs.promises.readdir(current.absolutePath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(current.absolutePath, entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth >= 2 || isIgnoredDirectoryName(entry.name)) {
+          continue;
+        }
+        queue.push({ absolutePath: entryPath, depth: current.depth + 1 });
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (sourceFileExtensions.has(path.extname(entry.name).toLowerCase())) {
+        sourceFileCount += 1;
+      }
+      if (current.depth === 0 && publicEntrypointNames.has(entry.name.toLowerCase())) {
+        hasPublicEntrypoint = true;
+      }
+    }
+  }
+  return { sourceFileCount, hasPublicEntrypoint };
+}
+async function addModuleIfStrongCandidate(workspaceRoot, discovered, sourcePath, moduleId, options) {
+  const normalizedSourcePath = normalizePath(sourcePath);
+  const name = normalizedSourcePath.split("/").pop() ?? moduleId;
+  if (options?.allowNoisyNames !== true && isNoisyModuleName(name)) {
+    return;
+  }
+  const absolutePath = path.join(workspaceRoot, ...normalizedSourcePath.split("/"));
+  const inspected = await inspectPotentialModuleRoot(absolutePath);
+  const hasStrongEvidence = inspected.sourceFileCount >= 2 || inspected.hasPublicEntrypoint || isKnownNestedModuleRoot(normalizedSourcePath);
+  if (options?.requireStrongEvidence !== false && !hasStrongEvidence) {
+    return;
+  }
+  const normalizedModuleId = normalizePath(moduleId || toModuleIdFromPath(normalizedSourcePath, options?.fallbackRoot));
+  if (!normalizedModuleId || options?.allowNoisyNames !== true && isNoisyModuleName(normalizedModuleId.split("/").pop() ?? normalizedModuleId)) {
+    return;
+  }
+  if (!discovered.has(normalizedModuleId)) {
+    discovered.set(normalizedModuleId, {
+      moduleId: normalizedModuleId,
+      sourcePath: normalizedSourcePath
+    });
+  }
+}
+async function addChildrenFromRoot(workspaceRoot, discovered, rootRelativePath, options) {
+  const normalizedRoot = normalizePath(rootRelativePath);
+  const absoluteRoot = path.join(workspaceRoot, ...normalizedRoot.split("/"));
+  if (!await pathExists(absoluteRoot)) {
+    return;
+  }
+  const entries = (await import_node_fs.promises.readdir(absoluteRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !isIgnoredDirectoryName(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const sourcePath = `${normalizedRoot}/${entry.name}`;
+    const moduleId = options?.includeParentPrefix && options.parentId ? `${options.parentId}/${entry.name}` : toModuleIdFromPath(sourcePath, normalizedRoot);
+    await addModuleIfStrongCandidate(workspaceRoot, discovered, sourcePath, moduleId, {
+      fallbackRoot: normalizedRoot,
+      ...options?.requireStrongEvidence !== void 0 ? { requireStrongEvidence: options.requireStrongEvidence } : {},
+      ...options?.allowNoisyNames !== void 0 ? { allowNoisyNames: options.allowNoisyNames } : {}
+    });
+  }
+}
+async function addMonorepoContainerModules(workspaceRoot, discovered, container) {
+  const absoluteContainer = path.join(workspaceRoot, container);
+  if (!await pathExists(absoluteContainer)) {
+    return;
+  }
+  const entries = (await import_node_fs.promises.readdir(absoluteContainer, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !isIgnoredDirectoryName(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const packagePath = `${container}/${entry.name}`;
+    await addModuleIfStrongCandidate(workspaceRoot, discovered, packagePath, entry.name, {
+      requireStrongEvidence: false
+    });
+    for (const sourceRoot of [
+      `${packagePath}/src`,
+      `${packagePath}/src/modules`,
+      `${packagePath}/src/features`,
+      `${packagePath}/src/domain`,
+      `${packagePath}/src/domains`,
+      `${packagePath}/src/application`,
+      `${packagePath}/src/infrastructure`
+    ]) {
+      await addChildrenFromRoot(workspaceRoot, discovered, sourceRoot, {
+        parentId: entry.name,
+        includeParentPrefix: true
+      });
+    }
+  }
+}
+async function discoverHierarchicalModuleRoots(workspaceRoot, modulesRootRelativePath = "src/modules") {
+  const discovered = /* @__PURE__ */ new Map();
+  await addChildrenFromRoot(workspaceRoot, discovered, normalizePath(modulesRootRelativePath), {
+    requireStrongEvidence: false,
+    allowNoisyNames: normalizePath(modulesRootRelativePath) === "src"
+  });
+  for (const root of [
+    "src/modules",
+    "src/features",
+    "src/domain",
+    "src/domains",
+    "src/application",
+    "src/infrastructure"
+  ]) {
+    await addChildrenFromRoot(workspaceRoot, discovered, root);
+  }
+  for (const container of ["packages", "apps", "services"]) {
+    await addMonorepoContainerModules(workspaceRoot, discovered, container);
+  }
+  return [...discovered.values()].sort((left, right) => left.moduleId.localeCompare(right.moduleId));
+}
 async function discoverModuleRoots(workspaceRoot, modulesRootRelativePath = "src/modules") {
+  const hierarchicalModules = await discoverHierarchicalModuleRoots(workspaceRoot, modulesRootRelativePath);
+  if (hierarchicalModules.length > 0) {
+    return new Map(
+      hierarchicalModules.map((entry) => [
+        entry.moduleId,
+        path.join(workspaceRoot, ...entry.sourcePath.split("/"))
+      ])
+    );
+  }
   const moduleDirectories = await listModuleDirectoryNames(workspaceRoot, modulesRootRelativePath);
   const modulesRoot = path.join(workspaceRoot, ...modulesRootRelativePath.split("/"));
   return new Map(
@@ -214854,7 +215111,8 @@ function buildArchitectureContract(base, overrides) {
 }
 function buildDefaultModuleContractPath(moduleName, contract) {
   const contractsRoot = resolveContractsRootFromContract(contract);
-  return `${contractsRoot}/${moduleName}.contract.json`;
+  const safeModuleName = moduleName.replace(/\\/g, "/").split("/").map((segment) => segment.trim()).filter((segment) => segment.length > 0).join(".");
+  return `${contractsRoot}/${safeModuleName}.contract.json`;
 }
 async function loadArchitectureContract(workspaceRoot) {
   const configPath = path7.join(workspaceRoot, ".archpilot", "architecture.json");
@@ -214985,8 +215243,63 @@ var DependencyRulesConfigError = class extends Error {
 function normalizePath2(filePath) {
   return filePath.replace(/\\/g, "/");
 }
-function getModulesRoot(workspaceRoot, modulesRootRelativePath = "src/modules") {
-  return path8.join(workspaceRoot, ...modulesRootRelativePath.split("/"));
+function toSafeContractModuleFileStem(moduleName) {
+  return normalizePath2(moduleName).split("/").map((segment) => segment.trim()).filter((segment) => segment.length > 0).join(".");
+}
+function normalizeAbsolutePath(filePath) {
+  return normalizePath2(path8.resolve(filePath)).toLowerCase();
+}
+function isPathInsideOrEqual(childPath, parentPath) {
+  const child = normalizeAbsolutePath(childPath);
+  const parent = normalizeAbsolutePath(parentPath);
+  return child === parent || child.startsWith(`${parent}/`);
+}
+function isParentChildModuleRelationship(leftModule, rightModule) {
+  if (leftModule === rightModule) {
+    return false;
+  }
+  return leftModule.startsWith(`${rightModule}/`) || rightModule.startsWith(`${leftModule}/`);
+}
+function isPeerModuleImport(dependencyImport) {
+  return !isParentChildModuleRelationship(
+    dependencyImport.sourceModule,
+    dependencyImport.targetModule
+  );
+}
+function filterPeerModuleImports(imports) {
+  return imports.filter(isPeerModuleImport);
+}
+function buildModuleHierarchyEdges(moduleIds) {
+  const moduleIdSet = new Set(moduleIds);
+  const edges = [];
+  for (const moduleId of moduleIds) {
+    const parentModule = moduleId.split("/").slice(0, -1).map((_, index, segments) => segments.slice(0, segments.length - index).join("/")).find((candidate) => moduleIdSet.has(candidate));
+    if (!parentModule) {
+      continue;
+    }
+    edges.push({ parentModule, childModule: moduleId });
+  }
+  return edges.sort((left, right) => {
+    const parentCompare = left.parentModule.localeCompare(right.parentModule);
+    if (parentCompare !== 0) {
+      return parentCompare;
+    }
+    return left.childModule.localeCompare(right.childModule);
+  });
+}
+function buildChildModulesByParent(hierarchyEdges) {
+  const byParent = /* @__PURE__ */ new Map();
+  for (const edge of hierarchyEdges) {
+    const children = byParent.get(edge.parentModule) ?? /* @__PURE__ */ new Set();
+    children.add(edge.childModule);
+    byParent.set(edge.parentModule, children);
+  }
+  return new Map(
+    [...byParent.entries()].map(([parentModule, childModules]) => [
+      parentModule,
+      sortUnique2(childModules)
+    ])
+  );
 }
 function getScriptKind(filePath) {
   const extension = path8.extname(filePath).toLowerCase();
@@ -215020,6 +215333,14 @@ function usesPythonImportParser(adapter) {
 function supportsDependencyImportParsing(adapter) {
   return usesTypeScriptParser(adapter) || usesJavaImportParser(adapter) || usesPhpImportParser(adapter) || usesGoImportParser(adapter) || usesPythonImportParser(adapter);
 }
+async function pathExists4(targetPath) {
+  try {
+    await import_node_fs8.promises.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function readTextFileIfExists2(filePath) {
   try {
     return await import_node_fs8.promises.readFile(filePath, { encoding: "utf8" });
@@ -215027,6 +215348,95 @@ async function readTextFileIfExists2(filePath) {
     return void 0;
   }
 }
+async function readPackageName(packageJsonPath) {
+  const contents = await readTextFileIfExists2(packageJsonPath);
+  if (!contents) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(contents);
+    return typeof parsed.name === "string" && parsed.name.trim().length > 0 ? parsed.name.trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function buildWorkspacePackageAliasMap(workspaceRoot, moduleRoots) {
+  const aliases = [];
+  for (const [moduleId, moduleRoot] of [...moduleRoots.entries()].sort(
+    ([left], [right]) => left.localeCompare(right)
+  )) {
+    const packageName = await readPackageName(path8.join(moduleRoot, "package.json"));
+    if (!packageName) {
+      continue;
+    }
+    aliases.push({ packageName, moduleId, moduleRoot });
+  }
+  aliases.push(...await buildTsConfigPathAliasMap(workspaceRoot, moduleRoots));
+  return aliases.sort((left, right) => {
+    const lengthCompare = right.packageName.length - left.packageName.length;
+    if (lengthCompare !== 0) {
+      return lengthCompare;
+    }
+    return left.packageName.localeCompare(right.packageName);
+  });
+}
+async function buildTsConfigPathAliasMap(workspaceRoot, moduleRoots) {
+  const contents = await readTextFileIfExists2(path8.join(workspaceRoot, "tsconfig.json"));
+  if (!contents) {
+    return [];
+  }
+  let paths;
+  try {
+    const parsed = JSON.parse(contents);
+    paths = parsed.compilerOptions?.paths;
+  } catch {
+    return [];
+  }
+  if (!paths) {
+    return [];
+  }
+  const aliases = [];
+  for (const [aliasPattern, targetPatterns] of Object.entries(paths).sort(
+    ([left], [right]) => left.localeCompare(right)
+  )) {
+    if (!Array.isArray(targetPatterns)) {
+      continue;
+    }
+    const aliasPrefix = aliasPattern.replace(/\/\*$/u, "");
+    if (aliasPrefix.length === 0) {
+      continue;
+    }
+    for (const targetPattern of targetPatterns) {
+      if (typeof targetPattern !== "string" || targetPattern.trim().length === 0) {
+        continue;
+      }
+      const isWildcard = /\/\*$/u.test(aliasPattern) && /\/\*$/u.test(targetPattern);
+      const normalizedTarget = normalizePath2(targetPattern).replace(/\/\*$/u, "");
+      const absoluteTarget = path8.join(workspaceRoot, ...normalizedTarget.split("/"));
+      const moduleEntry = [...moduleRoots.entries()].filter(([, moduleRoot2]) => isPathInsideOrEqual(absoluteTarget, moduleRoot2)).sort((left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]))[0];
+      if (!moduleEntry) {
+        continue;
+      }
+      const [moduleId, moduleRoot] = moduleEntry;
+      if (isWildcard) {
+        aliases.push({
+          packageName: aliasPrefix,
+          moduleId,
+          moduleRoot,
+          targetRoot: absoluteTarget
+        });
+        continue;
+      }
+      aliases.push({
+        packageName: aliasPrefix,
+        moduleId,
+        moduleRoot,
+        targetFile: absoluteTarget
+      });
+    }
+  }
+  return aliases;
+}
 function validateDependencyModuleRules(moduleName, value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new DependencyRulesConfigError(
@@ -215086,8 +215496,44 @@ async function readDependencyRulesConfig(workspaceRoot) {
   }, {});
   return { modules };
 }
-async function findModuleRoots(workspaceRoot, modulesRootRelativePath = "src/modules") {
-  return discoverModuleRoots(workspaceRoot, modulesRootRelativePath);
+async function findModuleRoots(workspaceRoot, modulesRootRelativePath = "src/modules", architectureContract) {
+  const discoveredModuleRoots = await discoverModuleRoots(
+    workspaceRoot,
+    modulesRootRelativePath
+  );
+  const moduleRoots = /* @__PURE__ */ new Map();
+  const registryEntries = architectureContract?.modules ? Object.entries(architectureContract.modules).sort(
+    ([left], [right]) => left.localeCompare(right)
+  ) : [];
+  for (const [moduleName, moduleReference] of registryEntries) {
+    const configuredPath = moduleReference.path;
+    if (!configuredPath || typeof configuredPath !== "string") {
+      continue;
+    }
+    const normalizedConfiguredPath = normalizePath2(configuredPath);
+    if (/\.[a-z0-9]+$/iu.test(normalizedConfiguredPath)) {
+      continue;
+    }
+    const absolutePath = path8.join(
+      workspaceRoot,
+      ...normalizedConfiguredPath.split("/")
+    );
+    try {
+      const stats = await import_node_fs8.promises.stat(absolutePath);
+      if (stats.isDirectory()) {
+        moduleRoots.set(moduleName, absolutePath);
+      }
+    } catch {
+    }
+  }
+  for (const [moduleName, moduleRoot] of discoveredModuleRoots.entries()) {
+    if (!moduleRoots.has(moduleName)) {
+      moduleRoots.set(moduleName, moduleRoot);
+    }
+  }
+  return new Map(
+    [...moduleRoots.entries()].sort(([left], [right]) => left.localeCompare(right))
+  );
 }
 async function buildExplicitStandaloneModulePathMap(workspaceRoot, architectureContract) {
   const moduleRegistry = architectureContract?.modules && typeof architectureContract.modules === "object" && !Array.isArray(architectureContract.modules) ? architectureContract.modules : void 0;
@@ -215500,7 +215946,45 @@ async function resolveImportPath(basePath, adapter) {
   }
   return void 0;
 }
-async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath, moduleRoots, explicitStandaloneModuleByPath, sourceFilePath, importSpecifier, adapter) {
+function resolvePackageAliasRemainder(packageName, importSpecifier) {
+  if (importSpecifier === packageName) {
+    return "";
+  }
+  if (importSpecifier.startsWith(`${packageName}/`)) {
+    return importSpecifier.slice(packageName.length + 1);
+  }
+  return void 0;
+}
+async function resolveWorkspacePackageImportPath(importSpecifier, workspacePackageAliases, adapter) {
+  const packageAlias = workspacePackageAliases.map((alias2) => ({
+    alias: alias2,
+    remainder: resolvePackageAliasRemainder(alias2.packageName, importSpecifier)
+  })).sort((left, right) => {
+    const leftCanResolveRemainder = left.remainder !== void 0 && left.remainder.length > 0 && left.alias.targetRoot !== void 0;
+    const rightCanResolveRemainder = right.remainder !== void 0 && right.remainder.length > 0 && right.alias.targetRoot !== void 0;
+    if (leftCanResolveRemainder !== rightCanResolveRemainder) {
+      return leftCanResolveRemainder ? -1 : 1;
+    }
+    return 0;
+  }).find(
+    (candidate) => candidate.remainder !== void 0
+  );
+  if (!packageAlias) {
+    return void 0;
+  }
+  const { alias, remainder } = packageAlias;
+  if (remainder.length === 0) {
+    return resolveImportPath(alias.targetFile ?? alias.targetRoot ?? alias.moduleRoot, adapter);
+  }
+  if (alias.targetRoot) {
+    return resolveImportPath(
+      path8.join(alias.targetRoot, ...remainder.split("/").filter((segment) => segment.length > 0)),
+      adapter
+    );
+  }
+  return void 0;
+}
+async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath, moduleRoots, explicitStandaloneModuleByPath, workspacePackageAliases, sourceFilePath, importSpecifier, adapter) {
   let basePath;
   const normalizedModulesRoot = normalizePath2(modulesRootRelativePath).replace(/^\/+/, "");
   if (usesJavaImportParser(adapter) && !importSpecifier.startsWith(".")) {
@@ -215555,6 +216039,22 @@ async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath,
     basePath = path8.join(workspaceRoot, importSpecifier.slice(1));
   } else if (normalizedModulesRoot.startsWith("src/") && importSpecifier.startsWith(`${normalizedModulesRoot.slice("src/".length)}/`)) {
     basePath = path8.join(workspaceRoot, "src", importSpecifier);
+  } else {
+    const workspacePackageImportPath = await resolveWorkspacePackageImportPath(
+      importSpecifier,
+      workspacePackageAliases,
+      adapter
+    );
+    if (workspacePackageImportPath) {
+      basePath = workspacePackageImportPath;
+    } else {
+      const moduleImportTarget = [...moduleRoots.entries()].filter(([moduleId]) => importSpecifier === moduleId || importSpecifier.startsWith(`${moduleId}/`)).sort((left, right) => right[0].length - left[0].length || left[0].localeCompare(right[0]))[0];
+      if (moduleImportTarget) {
+        const [moduleId, moduleRoot] = moduleImportTarget;
+        const remainder = importSpecifier === moduleId ? "" : importSpecifier.slice(moduleId.length + 1);
+        basePath = path8.join(moduleRoot, ...remainder.split("/").filter((segment) => segment.length > 0));
+      }
+    }
   }
   if (!basePath) {
     return void 0;
@@ -215563,17 +216063,8 @@ async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath,
   if (!resolvedPath) {
     return void 0;
   }
-  const modulesRoot = getModulesRoot(workspaceRoot, modulesRootRelativePath);
-  const relativeToModulesRoot = normalizePath2(path8.relative(modulesRoot, resolvedPath));
-  if (relativeToModulesRoot === "" || relativeToModulesRoot.startsWith("../") || relativeToModulesRoot.startsWith("..\\")) {
-    return void 0;
-  }
-  const segments = relativeToModulesRoot.split("/");
-  if (segments.length === 0) {
-    return void 0;
-  }
-  const targetModule = segments[0];
-  if (!moduleRoots.has(targetModule)) {
+  const targetModuleEntry = [...moduleRoots.entries()].filter(([, moduleRoot]) => isPathInsideOrEqual(resolvedPath, moduleRoot)).sort((left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]))[0];
+  if (!targetModuleEntry) {
     const standaloneTargetModule = explicitStandaloneModuleByPath.get(
       normalizePath2(path8.relative(workspaceRoot, resolvedPath))
     );
@@ -215586,11 +216077,18 @@ async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath,
       isPublicImport: true
     };
   }
-  const targetSubPath = segments.slice(1).join("/");
+  const [targetModule, targetModuleRoot] = targetModuleEntry;
+  const targetSubPath = normalizePath2(path8.relative(targetModuleRoot, resolvedPath));
+  if (targetSubPath === "" || targetSubPath.startsWith("../") || targetSubPath.startsWith("..\\")) {
+    return void 0;
+  }
   const indexEntrypointCandidates = adapter.dependencyParsingFileExtensions.map(
     (extension) => `index${extension}`
   );
-  const isPublicImport = indexEntrypointCandidates.includes(targetSubPath) || adapter.publicEntrypointDirectoryNames.some(
+  const nestedIndexEntrypointCandidates = adapter.dependencyParsingFileExtensions.flatMap(
+    (extension) => [`src/index${extension}`, `public/index${extension}`]
+  );
+  const isPublicImport = indexEntrypointCandidates.includes(targetSubPath) || nestedIndexEntrypointCandidates.includes(targetSubPath) || adapter.publicEntrypointDirectoryNames.some(
     (dirName) => targetSubPath.startsWith(`${dirName}/`)
   );
   return {
@@ -215599,7 +216097,7 @@ async function resolveCrossModuleImport(workspaceRoot, modulesRootRelativePath,
     isPublicImport
   };
 }
-async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath, moduleRoots, explicitStandaloneModuleByPath, adapter, options) {
+async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath, moduleRoots, explicitStandaloneModuleByPath, workspacePackageAliases, adapter, options) {
   const imports = [];
   const includeTestFiles = options?.includeTestFiles === true;
   if (!supportsDependencyImportParsing(adapter)) {
@@ -215608,7 +216106,10 @@ async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath,
   for (const [moduleName, moduleRoot] of [...moduleRoots.entries()].sort(
     ([left], [right]) => left.localeCompare(right)
   )) {
-    const sourceFiles = await collectSourceFiles(moduleRoot, adapter);
+    const childModuleRoots = [...moduleRoots.entries()].filter(([childModuleName, childModuleRoot]) => childModuleName !== moduleName && isPathInsideOrEqual(childModuleRoot, moduleRoot)).map(([, childModuleRoot]) => childModuleRoot);
+    const sourceFiles = (await collectSourceFiles(moduleRoot, adapter)).filter(
+      (sourceFile) => !childModuleRoots.some((childModuleRoot) => isPathInsideOrEqual(sourceFile, childModuleRoot))
+    );
     for (const sourceFilePath of sourceFiles) {
       const sourceFileRelativePath = normalizePath2(
         path8.relative(workspaceRoot, sourceFilePath)
@@ -215631,6 +216132,7 @@ async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath,
           modulesRootRelativePath,
           moduleRoots,
           explicitStandaloneModuleByPath,
+          workspacePackageAliases,
           sourceFilePath,
           importReference.specifier,
           adapter
@@ -215776,7 +216278,7 @@ async function loadModuleArchitectureContract(workspaceRoot, architectureContrac
   const registryEntry = architectureContract.modules[moduleName];
   const contractPath = registryEntry?.contract ?? path8.posix.join(
     resolveContractsRootFromContract(architectureContract),
-    `${moduleName}.contract.json`
+    `${toSafeContractModuleFileStem(moduleName)}.contract.json`
   );
   const fullContractPath = path8.join(workspaceRoot, ...contractPath.split("/"));
   const content = await readTextFileIfExists2(fullContractPath);
@@ -215862,11 +216364,89 @@ function isImportWithinPublicEntrypoints(resolvedTargetRelativePath, publicEntry
       }
     }
   }
-  return false;
+  return false;
+}
+async function filterExistingPublicEntrypoints(workspaceRoot, publicEntrypoints) {
+  const existingEntrypoints = [];
+  for (const publicEntrypoint of normalizePathList([...publicEntrypoints])) {
+    const absolutePath = path8.join(workspaceRoot, ...publicEntrypoint.split("/"));
+    if (await pathExists4(absolutePath)) {
+      existingEntrypoints.push(publicEntrypoint);
+    }
+  }
+  return existingEntrypoints;
+}
+async function inferExistingPublicEntrypointsFromModuleRoot(workspaceRoot, moduleRoot) {
+  if (!moduleRoot) {
+    return [];
+  }
+  const candidateSubpaths = [
+    "index.ts",
+    "index.tsx",
+    "index.js",
+    "index.jsx",
+    "src/index.ts",
+    "src/index.tsx",
+    "src/index.js",
+    "src/index.jsx",
+    "public/index.ts",
+    "public/index.tsx",
+    "public/index.js",
+    "public/index.jsx"
+  ];
+  const existingEntrypoints = [];
+  for (const candidateSubpath of candidateSubpaths) {
+    const candidatePath = path8.join(moduleRoot, ...candidateSubpath.split("/"));
+    if (await pathExists4(candidatePath)) {
+      existingEntrypoints.push(
+        normalizePath2(path8.relative(workspaceRoot, candidatePath))
+      );
+    }
+  }
+  return existingEntrypoints.sort((left, right) => left.localeCompare(right));
+}
+async function resolveModulePublicEntrypoints(workspaceRoot, architectureContract, moduleName, targetContract, moduleRoots) {
+  const registryPublicEntrypoints = architectureContract.modules[moduleName]?.publicEntrypoints ?? [];
+  const explicitPublicEntrypoints = sortUnique2([
+    ...registryPublicEntrypoints,
+    ...targetContract.publicEntrypoints
+  ]);
+  const existingExplicitEntrypoints = await filterExistingPublicEntrypoints(
+    workspaceRoot,
+    explicitPublicEntrypoints
+  );
+  if (existingExplicitEntrypoints.length > 0) {
+    return existingExplicitEntrypoints;
+  }
+  return inferExistingPublicEntrypointsFromModuleRoot(
+    workspaceRoot,
+    moduleRoots.get(moduleName)
+  );
+}
+function labelPublicEntrypoint(publicEntrypoint) {
+  const normalizedEntrypoint = normalizePath2(publicEntrypoint);
+  const fileName = normalizedEntrypoint.split("/").at(-1) ?? "";
+  return /^index\.[cm]?[jt]sx?$/iu.test(fileName) ? `${fileName} public entrypoint` : "public entrypoint";
 }
-function buildModuleIndexEntrypointPath(modulesRootRelativePath, moduleName, adapter) {
-  const entrypointFileName = adapter.scaffoldingDefaults?.moduleIndexFileName ?? "index.ts";
-  return normalizePath2(`${modulesRootRelativePath}/${moduleName}/${entrypointFileName}`);
+function describePublicEntrypointTargets(publicEntrypoints) {
+  if (publicEntrypoints.length <= 1) {
+    return publicEntrypoints[0] ?? "unknown public entrypoint";
+  }
+  return publicEntrypoints.join(", ");
+}
+async function describeModulePublicImportGuidance(workspaceRoot, moduleName, moduleRoots) {
+  const moduleRoot = moduleRoots.get(moduleName);
+  const inferredEntrypoints = await inferExistingPublicEntrypointsFromModuleRoot(
+    workspaceRoot,
+    moduleRoot
+  );
+  if (inferredEntrypoints.length > 0) {
+    return `Use the public entrypoint at ${describePublicEntrypointTargets(inferredEntrypoints)} instead.`;
+  }
+  if (moduleRoot) {
+    return `Use an existing public entrypoint under ${normalizePath2(path8.relative(workspaceRoot, moduleRoot))} instead.`;
+  }
+  return "Use an existing target module public entrypoint instead.";
 }
 function buildActualImportedModuleSetBySource(imports, registeredModuleIds) {
   const bySource = /* @__PURE__ */ new Map();
@@ -215918,11 +216498,19 @@ function buildInboundDependencyMap(bySource, moduleIds) {
 async function buildDependencyGraphSummary(workspaceRoot, architectureContract, options) {
   const modulesRoot = options?.modulesRootRelativePath ?? resolveModulesRootFromContract(architectureContract);
   const adapter = resolvePrimaryAdapterFromContract(architectureContract);
-  const moduleRoots = await findModuleRoots(workspaceRoot, modulesRoot);
+  const moduleRoots = await findModuleRoots(
+    workspaceRoot,
+    modulesRoot,
+    architectureContract
+  );
   const explicitStandaloneModuleByPath = await buildExplicitStandaloneModulePathMap(
     workspaceRoot,
     architectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(
+    workspaceRoot,
+    moduleRoots
+  );
   const moduleIds = sortUnique2([...moduleRoots.keys(), ...explicitStandaloneModuleByPath.values()]);
   const registeredModuleIds = new Set(moduleIds);
   const imports = await collectCrossModuleImports(
@@ -215930,9 +216518,11 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
     modulesRoot,
     moduleRoots,
     explicitStandaloneModuleByPath,
+    workspacePackageAliases,
     adapter
   );
-  const actualBySource = buildActualImportedModuleSetBySource(imports, registeredModuleIds);
+  const peerImports = filterPeerModuleImports(imports);
+  const actualBySource = buildActualImportedModuleSetBySource(peerImports, registeredModuleIds);
   const moduleContractCache = /* @__PURE__ */ new Map();
   const declaredBySource = /* @__PURE__ */ new Map();
   const hasContractByModule = /* @__PURE__ */ new Map();
@@ -215950,7 +216540,7 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
         new Set(
           sortUnique2(
             sourceContract.contract.dependsOn.filter(
-              (dependencyModule) => registeredModuleIds.has(dependencyModule)
+              (dependencyModule) => registeredModuleIds.has(dependencyModule) && !isParentChildModuleRelationship(moduleId, dependencyModule)
             )
           )
         )
@@ -215962,6 +216552,11 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
   }
   const inboundDeclared = buildInboundDependencyMap(declaredBySource, moduleIds);
   const inboundActual = buildInboundDependencyMap(actualBySource, moduleIds);
+  const hierarchyEdges = buildModuleHierarchyEdges(moduleIds);
+  const childModulesByParent = buildChildModulesByParent(hierarchyEdges);
+  const parentModuleByChild = new Map(
+    hierarchyEdges.map((edge) => [edge.childModule, edge.parentModule])
+  );
   return {
     modules: moduleIds.map((moduleId) => {
       const declaredDependencies = sortUnique2(declaredBySource.get(moduleId) ?? []);
@@ -215975,6 +216570,8 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
       return {
         module: moduleId,
         hasContract: hasContractByModule.get(moduleId) ?? false,
+        ...parentModuleByChild.has(moduleId) ? { parentModule: parentModuleByChild.get(moduleId) } : {},
+        childModules: childModulesByParent.get(moduleId) ?? [],
         declaredDependencies,
         actualDependencies,
         inboundDeclaredFrom: inboundDeclared.get(moduleId) ?? [],
@@ -215982,7 +216579,8 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
         unusedDeclaredDependencies,
         undeclaredActualDependencies
       };
-    })
+    }),
+    hierarchyEdges
   };
 }
 async function validateDependencyContractBoundaries(workspaceRoot, architectureContract, options) {
@@ -215991,24 +216589,34 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
   }
   const modulesRoot = options.modulesRootRelativePath ?? resolveModulesRootFromContract(architectureContract);
   const adapter = resolvePrimaryAdapterFromContract(architectureContract);
-  const moduleRoots = await findModuleRoots(workspaceRoot, modulesRoot);
+  const moduleRoots = await findModuleRoots(
+    workspaceRoot,
+    modulesRoot,
+    architectureContract
+  );
   const explicitStandaloneModuleByPath = await buildExplicitStandaloneModulePathMap(
     workspaceRoot,
     architectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(
+    workspaceRoot,
+    moduleRoots
+  );
   const imports = await collectCrossModuleImports(
     workspaceRoot,
     modulesRoot,
     moduleRoots,
     explicitStandaloneModuleByPath,
+    workspacePackageAliases,
     adapter
   );
+  const peerImports = filterPeerModuleImports(imports);
   const findings = [];
   const moduleContractCache = /* @__PURE__ */ new Map();
   if (options.checkDeclaredDependencies) {
     const failures = [];
     const skippedFindings = /* @__PURE__ */ new Map();
-    for (const dependencyImport of imports) {
+    for (const dependencyImport of peerImports) {
       const sourceContract = await loadModuleArchitectureContract(
         workspaceRoot,
         architectureContract,
@@ -216050,6 +216658,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
             ),
             filePath: dependencyImport.sourceFileRelativePath,
             line: dependencyImport.line,
+            importSpecifier: dependencyImport.importSpecifier,
             findingType: "module-dependency",
             module: dependencyImport.sourceModule,
             target: dependencyImport.targetModule
@@ -216072,6 +216681,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
           ),
           filePath: dependencyImport.sourceFileRelativePath,
           line: dependencyImport.line,
+          importSpecifier: dependencyImport.importSpecifier,
           findingType: "module-dependency",
           module: dependencyImport.sourceModule,
           target: dependencyImport.targetModule
@@ -216080,7 +216690,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     }
     if (failures.length > 0) {
       findings.push(...failures);
-    } else if (imports.length === 0) {
+    } else if (peerImports.length === 0) {
       findings.push({
         result: makeValidationResult(
           "AP-DEP-004",
@@ -216105,7 +216715,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
   if (options.checkPublicSurfaceImports) {
     const failures = [];
     const skippedFindings = /* @__PURE__ */ new Map();
-    for (const dependencyImport of imports) {
+    for (const dependencyImport of peerImports) {
       const sourceContract = await loadModuleArchitectureContract(
         workspaceRoot,
         architectureContract,
@@ -216165,6 +216775,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
             ),
             filePath: dependencyImport.sourceFileRelativePath,
             line: dependencyImport.line,
+            importSpecifier: dependencyImport.importSpecifier,
             findingType: "module-dependency",
             module: dependencyImport.sourceModule,
             target: dependencyImport.targetModule
@@ -216172,41 +216783,31 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
         }
         continue;
       }
-      if (targetContract.contract.publicEntrypoints.length > 0 && normalizePath2(dependencyImport.resolvedTargetRelativePath) !== buildModuleIndexEntrypointPath(
-        modulesRoot,
+      const publicEntrypoints = await resolveModulePublicEntrypoints(
+        workspaceRoot,
+        architectureContract,
         dependencyImport.targetModule,
-        adapter
-      )) {
-        failures.push({
-          result: makeValidationResult(
-            "AP-DEP-005",
-            "error",
-            false,
-            `Module '${dependencyImport.sourceModule}' must import module '${dependencyImport.targetModule}' via its index.ts public entrypoint: ${buildModuleIndexEntrypointPath(modulesRoot, dependencyImport.targetModule, adapter)}.`,
-            {
-              findingType: "module-dependency",
-              module: dependencyImport.sourceModule,
-              target: dependencyImport.targetModule
-            }
-          ),
-          filePath: dependencyImport.sourceFileRelativePath,
-          line: dependencyImport.line,
-          findingType: "module-dependency",
-          module: dependencyImport.sourceModule,
-          target: dependencyImport.targetModule
-        });
+        targetContract.contract,
+        moduleRoots
+      );
+      if (publicEntrypoints.length === 0) {
+        continue;
+      }
+      if (options.suppressPublicSurfaceFailuresForNonPublicImports === true && !dependencyImport.isPublicImport) {
         continue;
       }
-      if (targetContract.contract.publicEntrypoints.length === 0 && !isImportWithinPublicEntrypoints(
+      if (!isImportWithinPublicEntrypoints(
         dependencyImport.resolvedTargetRelativePath,
-        targetContract.contract.publicEntrypoints
+        publicEntrypoints
       )) {
+        const publicEntrypointLabel = labelPublicEntrypoint(publicEntrypoints[0] ?? "");
+        const expectedEntrypoint = describePublicEntrypointTargets(publicEntrypoints);
         failures.push({
           result: makeValidationResult(
             "AP-DEP-005",
             "error",
             false,
-            `Module '${dependencyImport.sourceModule}' imports a non-public path from module '${dependencyImport.targetModule}': ${dependencyImport.resolvedTargetRelativePath}`,
+            `Module '${dependencyImport.sourceModule}' must import module '${dependencyImport.targetModule}' via its ${publicEntrypointLabel}: ${expectedEntrypoint}.`,
             {
               findingType: "module-dependency",
               module: dependencyImport.sourceModule,
@@ -216215,6 +216816,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
           ),
           filePath: dependencyImport.sourceFileRelativePath,
           line: dependencyImport.line,
+          importSpecifier: dependencyImport.importSpecifier,
           findingType: "module-dependency",
           module: dependencyImport.sourceModule,
           target: dependencyImport.targetModule
@@ -216223,7 +216825,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     }
     if (failures.length > 0) {
       findings.push(...failures);
-    } else if (imports.length === 0) {
+    } else if (peerImports.length === 0) {
       findings.push({
         result: makeValidationResult(
           "AP-DEP-005",
@@ -216252,7 +216854,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
       ...explicitStandaloneModuleByPath.values()
     ]);
     const importedBySource = buildActualImportedModuleSetBySource(
-      imports,
+      peerImports,
       registeredModuleIds
     );
     for (const moduleName of [...registeredModuleIds].sort(
@@ -216267,7 +216869,9 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
       if (sourceContract.status !== "ok" || !sourceContract.contract) {
         continue;
       }
-      const declaredDependencies = [...sourceContract.contract.dependsOn].filter((dependencyModule) => registeredModuleIds.has(dependencyModule)).sort((left, right) => left.localeCompare(right));
+      const declaredDependencies = [...sourceContract.contract.dependsOn].filter(
+        (dependencyModule) => registeredModuleIds.has(dependencyModule) && !isParentChildModuleRelationship(moduleName, dependencyModule)
+      ).sort((left, right) => left.localeCompare(right));
       if (declaredDependencies.length === 0) {
         continue;
       }
@@ -216317,18 +216921,28 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
   const parsedArchitectureContract = await loadArchitectureContract(workspaceRoot);
   const adapter = resolvePrimaryAdapterFromContract(parsedArchitectureContract);
   const modulesRootRelativePath = options.modulesRootRelativePath ?? resolveModulesRootFromContract(parsedArchitectureContract);
-  const moduleRoots = await findModuleRoots(workspaceRoot, modulesRootRelativePath);
+  const moduleRoots = await findModuleRoots(
+    workspaceRoot,
+    modulesRootRelativePath,
+    parsedArchitectureContract
+  );
   const explicitStandaloneModuleByPath = await buildExplicitStandaloneModulePathMap(
     workspaceRoot,
     parsedArchitectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(
+    workspaceRoot,
+    moduleRoots
+  );
   const imports = await collectCrossModuleImports(
     workspaceRoot,
     modulesRootRelativePath,
     moduleRoots,
     explicitStandaloneModuleByPath,
+    workspacePackageAliases,
     adapter
   );
+  const peerImports = filterPeerModuleImports(imports);
   const findings = [];
   let dependencyRules;
   let dependencyRulesSkipReason;
@@ -216349,7 +216963,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
     }
   }
   if (options.checkCircularDependencies) {
-    const cycles = detectCircularDependencies([...moduleRoots.keys()], imports);
+    const cycles = detectCircularDependencies([...moduleRoots.keys()], peerImports);
     if (cycles.length === 0) {
       findings.push({
         result: makeValidationResult(
@@ -216381,7 +216995,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
         })
       );
     } else {
-      const violations = imports.filter((dependencyImport) => {
+      const violations = peerImports.filter((dependencyImport) => {
         const moduleRules = dependencyRules.modules[dependencyImport.sourceModule];
         if (!moduleRules) {
           return false;
@@ -216416,6 +217030,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
             ),
             filePath: violation.sourceFileRelativePath,
             line: violation.line,
+            importSpecifier: violation.importSpecifier,
             findingType: "module-dependency",
             module: violation.sourceModule,
             target: violation.targetModule
@@ -216433,7 +217048,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
         })
       );
     } else {
-      const violations = imports.filter((dependencyImport) => {
+      const violations = peerImports.filter((dependencyImport) => {
         const moduleRules = dependencyRules.modules[dependencyImport.sourceModule];
         return moduleRules?.publicEntrypointsOnly === true && !dependencyImport.isPublicImport;
       });
@@ -216448,12 +217063,17 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
         });
       } else {
         for (const violation of violations) {
+          const publicImportGuidance = await describeModulePublicImportGuidance(
+            workspaceRoot,
+            violation.targetModule,
+            moduleRoots
+          );
           findings.push({
             result: makeValidationResult(
               "AP-DEP-003",
               "error",
               false,
-              `${violation.sourceFileRelativePath}:${violation.line} imports non-public path "${violation.importSpecifier}" from module "${violation.targetModule}". Use the public entrypoint at ${modulesRootRelativePath}/${violation.targetModule} or ${modulesRootRelativePath}/${violation.targetModule}/public instead.`,
+              `${violation.sourceFileRelativePath}:${violation.line} imports non-public path "${violation.importSpecifier}" from module "${violation.targetModule}". ${publicImportGuidance}`,
               {
                 findingType: "module-dependency",
                 module: violation.sourceModule,
@@ -216462,6 +217082,7 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
             ),
             filePath: violation.sourceFileRelativePath,
             line: violation.line,
+            importSpecifier: violation.importSpecifier,
             findingType: "module-dependency",
             module: violation.sourceModule,
             target: violation.targetModule
@@ -216476,11 +217097,19 @@ async function buildModuleDependencyGraphSnapshot(workspaceRoot, options) {
   const parsedArchitectureContract = await loadArchitectureContract(workspaceRoot);
   const adapter = resolvePrimaryAdapterFromContract(parsedArchitectureContract);
   const modulesRootRelativePath = options?.modulesRootRelativePath ?? resolveModulesRootFromContract(parsedArchitectureContract);
-  const moduleRoots = await findModuleRoots(workspaceRoot, modulesRootRelativePath);
+  const moduleRoots = await findModuleRoots(
+    workspaceRoot,
+    modulesRootRelativePath,
+    parsedArchitectureContract
+  );
   const explicitStandaloneModuleByPath = await buildExplicitStandaloneModulePathMap(
     workspaceRoot,
     parsedArchitectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(
+    workspaceRoot,
+    moduleRoots
+  );
   const discoveredModules = sortUnique2([
     ...moduleRoots.keys(),
     ...explicitStandaloneModuleByPath.values()
@@ -216493,9 +217122,10 @@ async function buildModuleDependencyGraphSnapshot(workspaceRoot, options) {
     modulesRootRelativePath,
     moduleRoots,
     explicitStandaloneModuleByPath,
+    workspacePackageAliases,
     adapter
   );
-  const imports = allImports.filter(
+  const imports = filterPeerModuleImports(allImports).filter(
     (dependencyImport) => moduleSet.has(dependencyImport.sourceModule) && moduleSet.has(dependencyImport.targetModule)
   ).sort((left, right) => {
     const sourceCompare = left.sourceModule.localeCompare(right.sourceModule);
@@ -216548,6 +217178,7 @@ async function buildModuleDependencyGraphSnapshot(workspaceRoot, options) {
   return {
     modules,
     edges,
+    hierarchyEdges: buildModuleHierarchyEdges(modules),
     cycles,
     imports
   };
@@ -216572,7 +217203,7 @@ function normalizeStringArray(value) {
   }
   return normalizedValues;
 }
-async function pathExists4(targetPath) {
+async function pathExists5(targetPath) {
   try {
     await import_node_fs9.promises.access(targetPath);
     return true;
@@ -216708,7 +217339,7 @@ async function validateModuleContractIntegrity(workspaceRoot, contract, options)
       if (!moduleReference.contract) {
         continue;
       }
-      const exists = await pathExists4(
+      const exists = await pathExists5(
         toWorkspaceAbsolutePath(workspaceRoot, moduleReference.contract)
       );
       if (!exists) {
@@ -216744,7 +217375,7 @@ async function validateModuleContractIntegrity(workspaceRoot, contract, options)
       }
       const contractPath = moduleReference.contract;
       const fullContractPath = toWorkspaceAbsolutePath(workspaceRoot, contractPath);
-      if (!await pathExists4(fullContractPath)) {
+      if (!await pathExists5(fullContractPath)) {
         continue;
       }
       const parsedContract = await readModuleContract(workspaceRoot, contractPath);
@@ -216803,7 +217434,7 @@ async function validateModuleContractIntegrity(workspaceRoot, contract, options)
       }
       const contractPath = moduleReference.contract;
       const fullContractPath = toWorkspaceAbsolutePath(workspaceRoot, contractPath);
-      if (!await pathExists4(fullContractPath)) {
+      if (!await pathExists5(fullContractPath)) {
         continue;
       }
       const parsedContract = await readModuleContract(workspaceRoot, contractPath);
@@ -217161,7 +217792,7 @@ function hasKeywordMatch(record, keywords) {
   const haystack = `${record.fileName} ${record.title}`.toLowerCase();
   return keywords.some((keyword) => haystack.includes(keyword));
 }
-function pathExists5(targetPath) {
+function pathExists6(targetPath) {
   return (0, import_promises.access)(targetPath).then(() => true).catch(() => false);
 }
 function buildSummary(records) {
@@ -217186,7 +217817,7 @@ function createAdrValidationResult(input2) {
 async function validateAdrEnforcement(workspaceRoot, config) {
   const adrDirectoryRelativePath = await resolveAdrDirectoryRelativePath(workspaceRoot);
   const adrDirectory = getAdrDirectoryPath(workspaceRoot, adrDirectoryRelativePath);
-  const adrDirectoryExists = await pathExists5(adrDirectory);
+  const adrDirectoryExists = await pathExists6(adrDirectory);
   if (!adrDirectoryExists) {
     return {
       results: [
@@ -217239,7 +217870,7 @@ async function validateAdrEnforcement(workspaceRoot, config) {
       }
     ]
   ];
-  const dependencyContextExists = await pathExists5(path11.join(workspaceRoot, ".archpilot", "dependency-rules.json")) || await pathExists5(path11.join(workspaceRoot, ".archpilot", "contracts"));
+  const dependencyContextExists = await pathExists6(path11.join(workspaceRoot, ".archpilot", "dependency-rules.json")) || await pathExists6(path11.join(workspaceRoot, ".archpilot", "contracts"));
   const checksToRun = [
     requiredCoverageChecks[0],
     ...dependencyContextExists ? [requiredCoverageChecks[1]] : [],
@@ -217750,13 +218381,6 @@ var overallSetupGapWarningPenalty = 1;
 var overallSetupGapInfoPenalty = 1;
 var minScore = 0;
 var maxScore = 100;
-var crossModuleDependencyRuleIds = /* @__PURE__ */ new Set([
-  "AP-DEP-002",
-  "AP-DEP-003",
-  "AP-DEP-004",
-  "AP-DEP-005",
-  "AP-DEP-010"
-]);
 var crossModuleContractRuleIds = /* @__PURE__ */ new Set(["AP-DEP-004", "AP-DEP-005"]);
 var cycleRuleIds = /* @__PURE__ */ new Set(["AP-DEP-001", "AP-DEP-008"]);
 function clampScore(value) {
@@ -217810,6 +218434,22 @@ function getQualityPenaltyForResult(result) {
   }
   return base + getAdditionalQualityPenalty(result);
 }
+function dedupeResultsByDeductionKey(results) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const result of results) {
+    if (!result.deductionKey) {
+      deduped.push(result);
+      continue;
+    }
+    if (seen.has(result.deductionKey)) {
+      continue;
+    }
+    seen.add(result.deductionKey);
+    deduped.push(result);
+  }
+  return deduped;
+}
 function getReadinessPenaltyForSetupGapSeverity(severity) {
   if (severity === "error") {
     return readinessSetupGapErrorPenalty;
@@ -217820,7 +218460,7 @@ function getReadinessPenaltyForSetupGapSeverity(severity) {
   return readinessSetupGapInfoPenalty;
 }
 function deriveGovernanceRiskLevelFromResults(results) {
-  const qualityFailures = results.filter(
+  const qualityFailures = dedupeResultsByDeductionKey(results).filter(
     (result) => !result.passed && (result.impact ?? "quality") === "quality"
   );
   const hasCriticalRule = qualityFailures.some(
@@ -217839,21 +218479,14 @@ function deriveGovernanceRiskLevelFromResults(results) {
 }
 function applyFinalScoreAdjustments(input2) {
   let adjusted = input2.baseScore;
-  const crossModuleDependencyViolations = input2.results.filter(
-    (result) => !result.passed && (result.impact ?? "quality") === "quality" && typeof result.ruleId === "string" && crossModuleDependencyRuleIds.has(result.ruleId)
-  ).length;
-  const crossModuleContractViolations = input2.results.filter(
+  const uniqueResults = dedupeResultsByDeductionKey(input2.results);
+  const crossModuleContractViolations = uniqueResults.filter(
     (result) => !result.passed && (result.impact ?? "quality") === "quality" && typeof result.ruleId === "string" && crossModuleContractRuleIds.has(result.ruleId)
   ).length;
-  const cycleViolations = input2.results.filter(
+  const cycleViolations = uniqueResults.filter(
     (result) => !result.passed && (result.impact ?? "quality") === "quality" && typeof result.ruleId === "string" && cycleRuleIds.has(result.ruleId)
   ).length;
-  const blockingViolations = input2.results.filter(
-    (result) => !result.passed && result.severity === "error" && (result.impact ?? "quality") === "quality"
-  ).length;
-  adjusted -= Math.min(8, blockingViolations * 2);
   adjusted -= Math.min(6, crossModuleContractViolations * 2);
-  adjusted -= Math.min(4, crossModuleDependencyViolations);
   adjusted -= Math.min(4, cycleViolations * 2);
   const governanceRiskLevel = input2.context?.governanceRiskLevel ?? deriveGovernanceRiskLevelFromResults(input2.results);
   if (governanceRiskLevel === "critical") {
@@ -219337,7 +219970,7 @@ function normalizeSqlTableName(raw) {
   }
   return trimmed;
 }
-async function pathExists6(targetPath) {
+async function pathExists7(targetPath) {
   try {
     await import_node_fs19.promises.access(targetPath);
     return true;
@@ -219358,7 +219991,7 @@ async function readTextFileIfReasonable(filePath) {
 }
 async function collectFilesRecursive(rootPath, includeFile, ignoredDirectoryNames8) {
   const collected = [];
-  if (!await pathExists6(rootPath)) {
+  if (!await pathExists7(rootPath)) {
     return collected;
   }
   const stack = [rootPath];
@@ -219949,11 +220582,11 @@ src/
   },
   DEP_ISOLATED_MODULE_DETECTED: {
     id: ValidationRuleIds.DEP_ISOLATED_MODULE_DETECTED,
-    title: "Isolated module detected",
+    title: "Potential orphan module detected",
     category: "dependency",
     defaultSeverity: "warning",
-    description: "Checks whether a registered module has no declared or actual inbound/outbound module dependencies.",
-    recommendedFix: "Connect the module to the architecture through legitimate dependencies, or remove it if it is unused."
+    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."
   },
   DEP_TRANSITIVE_CIRCULAR_MODULE_DEPENDENCY: {
     id: ValidationRuleIds.DEP_TRANSITIVE_CIRCULAR_MODULE_DEPENDENCY,
@@ -220242,6 +220875,23 @@ function buildSetupGapDeductionKeyFromMessage(message) {
   }
   return void 0;
 }
+function buildDependencyDeductionKey(result) {
+  if (result.findingType !== "module-dependency") {
+    return void 0;
+  }
+  if (typeof result.sourceFile !== "string" || typeof result.sourceLine !== "number" || typeof result.module !== "string" || typeof result.target !== "string") {
+    return void 0;
+  }
+  return [
+    "quality",
+    result.id,
+    result.module,
+    result.target,
+    result.sourceFile.replace(/\\/g, "/"),
+    String(result.sourceLine),
+    result.importSpecifier ?? ""
+  ].join("|");
+}
 function classifyValidationResult(result) {
   if (result.passed) {
     return {
@@ -220269,7 +220919,7 @@ function classifyValidationResult(result) {
   return {
     kind: "violation",
     scoreImpact: "quality",
-    deductionKey: `quality:${result.id}:${normalizedMessage}`
+    deductionKey: buildDependencyDeductionKey(result) ?? `quality:${result.id}:${normalizedMessage}`
   };
 }
 function getRuleIdSet() {
@@ -220859,7 +221509,7 @@ function applyValidationExceptions(results, exceptions) {
     approvedExceptions: dedupedApprovedExceptions
   };
 }
-async function pathExists7(targetPath) {
+async function pathExists8(targetPath) {
   try {
     await import_node_fs20.promises.access(targetPath);
     return true;
@@ -220898,11 +221548,11 @@ async function readDependencyRulesRawConfig(workspaceRoot) {
 async function resolveValidationConfigPath(workspaceRoot) {
   const configDir = path21.join(workspaceRoot, ".archpilot");
   const jsoncPath = path21.join(configDir, "validation-config.jsonc");
-  if (await pathExists7(jsoncPath)) {
+  if (await pathExists8(jsoncPath)) {
     return jsoncPath;
   }
   const jsonPath = path21.join(configDir, "validation-config.json");
-  if (await pathExists7(jsonPath)) {
+  if (await pathExists8(jsonPath)) {
     return jsonPath;
   }
   return void 0;
@@ -221028,7 +221678,7 @@ async function validateApiStyle(workspaceRoot, contract, config, validationConfi
   }
   const openApiRelativePath = resolveOpenApiRelativePath(contract);
   const openApiPath = path21.join(workspaceRoot, ...openApiRelativePath.split("/"));
-  const exists = await pathExists7(openApiPath);
+  const exists = await pathExists8(openApiPath);
   if (openApiRequired) {
     results.push({
       id: ValidationRuleIds.API_OPENAPI_EXISTS,
@@ -221081,7 +221731,7 @@ async function validateTenantModel(workspaceRoot, contract, config, validationCo
   if (config.tenantModel === "same_db_different_schema" && !isRuleDisabled(ValidationRuleIds.DOC_TENANT_DIFFERENT_SCHEMA_ADR, validationConfig)) {
     const tenantModelAdrRelativePath = resolveTenantModelAdrRelativePath(contract);
     const adrPath = path21.join(workspaceRoot, ...tenantModelAdrRelativePath.split("/"));
-    const exists = await pathExists7(adrPath);
+    const exists = await pathExists8(adrPath);
     results.push({
       id: ValidationRuleIds.DOC_TENANT_DIFFERENT_SCHEMA_ADR,
       severity: "warning",
@@ -221134,7 +221784,7 @@ async function validateArchitectureStyle(workspaceRoot, contract, validationConf
   if (implementationProfile === "typescript-backend" && !isRuleDisabled(ValidationRuleIds.ARCH_OVERVIEW_ARTIFACT_EXISTS, validationConfig)) {
     const overviewRelativePath = resolveOverviewRelativePath(contract);
     const overviewPath = path21.join(workspaceRoot, ...overviewRelativePath.split("/"));
-    const overviewExists = await pathExists7(overviewPath);
+    const overviewExists = await pathExists8(overviewPath);
     results.push({
       id: ValidationRuleIds.ARCH_OVERVIEW_ARTIFACT_EXISTS,
       severity: "error",
@@ -221146,7 +221796,7 @@ async function validateArchitectureStyle(workspaceRoot, contract, validationConf
     const normalizeEntrypoint = (entry) => normalizeRelativePath2(entry.trim());
     const hasDeclaredPublicEntrypoint = async (moduleName, entry) => {
       const entryPath = path21.join(workspaceRoot, ...normalizeEntrypoint(entry).split("/"));
-      return pathExists7(entryPath);
+      return pathExists8(entryPath);
     };
     const readModuleContractPublicEntrypoints = async (moduleName) => {
       const registryEntry = contract.modules[moduleName];
@@ -221171,9 +221821,18 @@ async function validateArchitectureStyle(workspaceRoot, contract, validationConf
     };
     const modulesRootRelativePath2 = await getConfiguredModulesRoot(workspaceRoot, contract);
     const modulesRoot = path21.join(workspaceRoot, ...modulesRootRelativePath2.split("/"));
-    if (await pathExists7(modulesRoot)) {
-      const moduleEntries = await import_node_fs20.promises.readdir(modulesRoot, { withFileTypes: true });
-      const moduleDirectories2 = moduleEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+    if (await pathExists8(modulesRoot)) {
+      const hierarchicalModules = await discoverHierarchicalModuleRoots(
+        workspaceRoot,
+        modulesRootRelativePath2
+      );
+      const moduleDirectories2 = hierarchicalModules.length > 0 ? hierarchicalModules.map((entry) => ({
+        moduleName: entry.moduleId,
+        sourcePath: entry.sourcePath
+      })) : (await import_node_fs20.promises.readdir(modulesRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => ({
+        moduleName: entry.name,
+        sourcePath: `${modulesRootRelativePath2}/${entry.name}`
+      })).sort((left, right) => left.moduleName.localeCompare(right.moduleName));
       const dependencySummary = await buildDependencyGraphSummary(workspaceRoot, contract, {
         modulesRootRelativePath: modulesRootRelativePath2
       });
@@ -221181,10 +221840,11 @@ async function validateArchitectureStyle(workspaceRoot, contract, validationConf
         dependencySummary.modules.filter((moduleSummary) => moduleSummary.inboundDeclaredFrom.length > 0).map((moduleSummary) => moduleSummary.module)
       );
       const incompleteModules = [];
-      for (const moduleName of moduleDirectories2) {
-        const moduleDir = path21.join(modulesRoot, moduleName);
-        const readmeExists = await pathExists7(path21.join(moduleDir, "README.md"));
-        const indexExists = await pathExists7(path21.join(moduleDir, "index.ts"));
+      for (const moduleDirectory of moduleDirectories2) {
+        const moduleName = moduleDirectory.moduleName;
+        const moduleDir = path21.join(workspaceRoot, ...moduleDirectory.sourcePath.split("/"));
+        const readmeExists = await pathExists8(path21.join(moduleDir, "README.md"));
+        const indexExists = await pathExists8(path21.join(moduleDir, "index.ts"));
         const registryPublicEntrypoints = (contract.modules[moduleName]?.publicEntrypoints ?? []).filter((entry) => typeof entry === "string").map((entry) => normalizeEntrypoint(entry));
         const contractPublicEntrypoints = await readModuleContractPublicEntrypoints(moduleName);
         const declaredPublicEntrypoints = [
@@ -221231,7 +221891,7 @@ async function validateDatabaseArtifacts(workspaceRoot, contract, config, valida
   }
   const sqlBaselineRelativePath = resolveSqlBaselineRelativePath(contract);
   const sqlBaselinePath = path21.join(workspaceRoot, ...sqlBaselineRelativePath.split("/"));
-  const exists = await pathExists7(sqlBaselinePath);
+  const exists = await pathExists8(sqlBaselinePath);
   results.push({
     id: ValidationRuleIds.DB_SQL_BASELINE_EXISTS,
     severity: "error",
@@ -221240,6 +221900,34 @@ async function validateDatabaseArtifacts(workspaceRoot, contract, config, valida
   });
   return results;
 }
+function buildDependencyFindingStableKey(finding) {
+  if (!finding.result.id || !finding.module || !finding.target || !finding.filePath || finding.line === void 0 || !finding.importSpecifier) {
+    return void 0;
+  }
+  return [
+    finding.result.id,
+    finding.module,
+    finding.target,
+    finding.filePath.replace(/\\/g, "/"),
+    String(finding.line),
+    finding.importSpecifier
+  ].join("|");
+}
+function dedupeDependencyFindings(findings) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const finding of findings) {
+    const stableKey = buildDependencyFindingStableKey(finding);
+    if (stableKey && seen.has(stableKey)) {
+      continue;
+    }
+    if (stableKey) {
+      seen.add(stableKey);
+    }
+    deduped.push(finding);
+  }
+  return deduped;
+}
 async function validateModuleDependencies(workspaceRoot, contract, validationConfig, onDependencyConfigError, dependencyRulesConfigOverride) {
   const modulesRootRelativePath = await getConfiguredModulesRoot(workspaceRoot, contract);
   const dependencyRuleChecks = {
@@ -221279,10 +221967,11 @@ async function validateModuleDependencies(workspaceRoot, contract, validationCon
       }),
       validateDependencyContractBoundaries(workspaceRoot, contract, {
         ...contractDependencyRuleChecks,
-        modulesRootRelativePath
+        modulesRootRelativePath,
+        suppressPublicSurfaceFailuresForNonPublicImports: dependencyRuleChecks.checkNonPublicImports
       })
     ]);
-    const findings = [...legacyFindings, ...contractFindings];
+    const findings = dedupeDependencyFindings([...legacyFindings, ...contractFindings]);
     const results = [];
     for (const finding of findings) {
       const resultWithSource = {
@@ -221293,7 +221982,8 @@ async function validateModuleDependencies(workspaceRoot, contract, validationCon
         ...finding.api ? { api: finding.api } : {},
         ...finding.findingType ? { findingType: finding.findingType } : {},
         ...finding.filePath ? { sourceFile: finding.filePath, filePath: finding.filePath } : {},
-        ...finding.line !== void 0 ? { sourceLine: finding.line } : {}
+        ...finding.line !== void 0 ? { sourceLine: finding.line } : {},
+        ...finding.importSpecifier ? { importSpecifier: finding.importSpecifier } : {}
       };
       results.push(resultWithSource);
     }
@@ -221311,24 +222001,117 @@ async function validateDependencyGraphIsolation(workspaceRoot, contract, depende
     return [];
   }
   const isolatedResults = [];
-  const isolationExemptInfrastructureModules = /* @__PURE__ */ new Set(["ci", "policy", "validation"]);
+  const sourceFileExtensions4 = /* @__PURE__ */ new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+    ".py",
+    ".go",
+    ".java",
+    ".kt",
+    ".kts",
+    ".cs",
+    ".php",
+    ".rb",
+    ".vue",
+    ".svelte"
+  ]);
   const isTestLikeModule = (moduleName) => {
     const normalized = moduleName.toLowerCase();
     return normalized === "test" || normalized === "tests" || normalized.endsWith("-test") || normalized.endsWith("-tests");
   };
+  const collectModuleSourceEvidence2 = async (directoryPath) => {
+    let entries;
+    try {
+      entries = await import_node_fs20.promises.readdir(directoryPath, { withFileTypes: true });
+    } catch {
+      return { sourceFileCount: 0, hasReadme: false, hasEntrypointFile: false };
+    }
+    let sourceFileCount = 0;
+    let hasReadme = false;
+    let hasEntrypointFile = false;
+    for (const entry of entries) {
+      const fullPath = path21.join(directoryPath, entry.name);
+      if (entry.isDirectory()) {
+        if (["node_modules", "dist", "out", "build", "coverage", ".git"].includes(entry.name)) {
+          continue;
+        }
+        const nested = await collectModuleSourceEvidence2(fullPath);
+        sourceFileCount += nested.sourceFileCount;
+        hasReadme ||= nested.hasReadme;
+        hasEntrypointFile ||= nested.hasEntrypointFile;
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const lowerName = entry.name.toLowerCase();
+      if (lowerName === "readme.md" || lowerName === "readme.mdx") {
+        hasReadme = true;
+      }
+      if (/^(index|main|app|extension|cli)\.[cm]?[jt]sx?$/iu.test(entry.name)) {
+        hasEntrypointFile = true;
+      }
+      if (sourceFileExtensions4.has(path21.extname(entry.name).toLowerCase())) {
+        sourceFileCount += 1;
+      }
+    }
+    return { sourceFileCount, hasReadme, hasEntrypointFile };
+  };
+  const readPackageJsonIfExists2 = async (moduleDirectoryPath) => {
+    const content = await readTextFileIfExists3(path21.join(moduleDirectoryPath, "package.json"));
+    if (!content) {
+      return void 0;
+    }
+    try {
+      const parsed = JSON.parse(content);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  const hasPackageEntrypoint2 = async (moduleDirectoryPath) => {
+    const packageJson = await readPackageJsonIfExists2(moduleDirectoryPath);
+    if (!packageJson) {
+      return false;
+    }
+    return ["main", "module", "browser", "types", "bin", "exports"].some(
+      (field) => packageJson[field] !== void 0
+    );
+  };
+  const hasKnownBoundaryRole2 = (moduleName) => {
+    const normalized = moduleName.toLowerCase();
+    const compact = normalized.replace(/[-_/]/gu, "");
+    const segments = normalized.split(/[/-]/u);
+    return ["adr", "ci", "compliance", "config", "governance", "policy", "validation", "smartinit"].some(
+      (role) => compact.includes(role) || segments.includes(role)
+    );
+  };
+  const hasConfiguredPublicEntrypoint2 = (moduleName) => {
+    const publicEntrypoints = contract.modules[moduleName]?.publicEntrypoints;
+    return Array.isArray(publicEntrypoints) && publicEntrypoints.some(
+      (entry) => typeof entry === "string" && entry.trim().length > 0
+    );
+  };
+  const hasIntentionalIndependentEvidence2 = async (moduleSummary, moduleDirectoryPath) => {
+    const sourceEvidence = await collectModuleSourceEvidence2(moduleDirectoryPath);
+    return moduleSummary.hasContract || hasConfiguredPublicEntrypoint2(moduleSummary.module) || sourceEvidence.hasReadme || sourceEvidence.hasEntrypointFile || await hasPackageEntrypoint2(moduleDirectoryPath) || moduleSummary.childModules.length > 0 || moduleSummary.parentModule !== void 0 && moduleSummary.childModules.length === 0 && sourceEvidence.sourceFileCount > 0 || hasKnownBoundaryRole2(moduleSummary.module) || sourceEvidence.sourceFileCount >= 2;
+  };
   for (const moduleSummary of dependencyGraphSummary.modules) {
     if (isTestLikeModule(moduleSummary.module)) {
       continue;
     }
-    if (isolationExemptInfrastructureModules.has(moduleSummary.module.toLowerCase())) {
-      continue;
-    }
     const registryEntry = contract.modules[moduleSummary.module];
     if (!registryEntry?.path) {
       continue;
     }
     const moduleDirectoryPath = path21.join(workspaceRoot, ...registryEntry.path.split("/"));
-    const moduleDirectoryExists = await pathExists7(moduleDirectoryPath);
+    const moduleDirectoryExists = await pathExists8(moduleDirectoryPath);
     if (!moduleDirectoryExists) {
       continue;
     }
@@ -221336,11 +222119,14 @@ async function validateDependencyGraphIsolation(workspaceRoot, contract, depende
     if (!isIsolated) {
       continue;
     }
+    if (await hasIntentionalIndependentEvidence2(moduleSummary, moduleDirectoryPath)) {
+      continue;
+    }
     isolatedResults.push({
       id: ValidationRuleIds.DEP_ISOLATED_MODULE_DETECTED,
       severity: "warning",
       passed: false,
-      message: `Module '${moduleSummary.module}' is isolated: it has no declared or actual inbound/outbound module dependencies.`,
+      message: `Module '${moduleSummary.module}' is a potential orphan: it has no declared or actual inbound/outbound module dependencies and little evidence of intentional architectural use.`,
       findingType: "module-dependency",
       module: moduleSummary.module
     });
@@ -221353,7 +222139,7 @@ async function validateDependencyGraphIsolation(workspaceRoot, contract, depende
       id: ValidationRuleIds.DEP_ISOLATED_MODULE_DETECTED,
       severity: "warning",
       passed: true,
-      message: "No isolated modules detected among registered modules with existing registry paths."
+      message: "No potential orphan modules detected among registered modules with existing registry paths."
     }
   ];
 }
@@ -222135,7 +222921,10 @@ function filterDependencyGraphSummaryByModuleScope(dependencyGraphSummary, modul
     )
   }));
   return {
-    modules: scopedModules
+    modules: scopedModules,
+    hierarchyEdges: dependencyGraphSummary.hierarchyEdges.filter(
+      (edge) => scopeSet.has(edge.parentModule) && scopeSet.has(edge.childModule)
+    )
   };
 }
 async function runArchitectureValidationForWorkspace(workspaceRoot, options) {
@@ -223892,7 +224681,7 @@ var import_node_fs22 = require("node:fs");
 async function ensureDirectory(directoryPath) {
   await import_node_fs22.promises.mkdir(directoryPath, { recursive: true });
 }
-async function pathExists8(targetPath) {
+async function pathExists9(targetPath) {
   try {
     await import_node_fs22.promises.access(targetPath);
     return true;
@@ -223901,7 +224690,7 @@ async function pathExists8(targetPath) {
   }
 }
 async function createFileIfMissing(filePath, content) {
-  if (await pathExists8(filePath)) {
+  if (await pathExists9(filePath)) {
     return false;
   }
   await ensureDirectory(path23.dirname(filePath));
@@ -224009,7 +224798,7 @@ async function previewArch001(context) {
   ];
   const filesCreated = [];
   for (const targetPath of targetPaths) {
-    if (!await pathExists8(targetPath)) {
+    if (!await pathExists9(targetPath)) {
       filesCreated.push(relative5(targetPath, context.workspaceRoot));
     }
   }
@@ -224030,7 +224819,7 @@ async function applyArch001(context) {
   ];
   const filesCreated = [];
   for (const targetPath of targetPaths) {
-    const existed = await pathExists8(targetPath);
+    const existed = await pathExists9(targetPath);
     await ensureDirectory(targetPath);
     if (!existed) {
       filesCreated.push(relative5(targetPath, context.workspaceRoot));
@@ -224046,8 +224835,8 @@ async function applyArch001(context) {
 async function previewArch003(context) {
   const directoryPath = path24.join(context.workspaceRoot, "docs", "architecture");
   const filePath = path24.join(directoryPath, "overview.md");
-  const directoryExists2 = await pathExists8(directoryPath);
-  const fileExists4 = await pathExists8(filePath);
+  const directoryExists2 = await pathExists9(directoryPath);
+  const fileExists4 = await pathExists9(filePath);
   const filesCreated = [];
   if (!directoryExists2) {
     filesCreated.push(relative5(directoryPath, context.workspaceRoot));
@@ -224066,7 +224855,7 @@ async function previewArch003(context) {
 async function applyArch003(context) {
   const directoryPath = path24.join(context.workspaceRoot, "docs", "architecture");
   const filePath = path24.join(directoryPath, "overview.md");
-  const directoryExisted = await pathExists8(directoryPath);
+  const directoryExisted = await pathExists9(directoryPath);
   const fileCreated = await createFileIfMissing(filePath, architectureOverviewStarterTemplate);
   const filesCreated = [];
   if (!directoryExisted) {
@@ -224084,7 +224873,7 @@ async function applyArch003(context) {
 }
 async function previewApi001(context) {
   const filePath = path24.join(context.workspaceRoot, "contracts", "openapi.yaml");
-  const exists = await pathExists8(filePath);
+  const exists = await pathExists9(filePath);
   return {
     filesCreated: exists ? [] : [relative5(filePath, context.workspaceRoot)],
     filesModified: [],
@@ -224125,7 +224914,7 @@ async function previewArch005(context) {
     };
   }
   const absolutePath = path24.join(context.workspaceRoot, ...modulePath.split("/"));
-  const exists = await pathExists8(absolutePath);
+  const exists = await pathExists9(absolutePath);
   return {
     filesCreated: exists ? [] : [modulePath],
     filesModified: [],
@@ -224144,7 +224933,7 @@ async function applyArch005(context) {
     };
   }
   const absolutePath = path24.join(context.workspaceRoot, ...modulePath.split("/"));
-  const existed = await pathExists8(absolutePath);
+  const existed = await pathExists9(absolutePath);
   await ensureDirectory(absolutePath);
   return {
     applied: !existed,
@@ -224165,7 +224954,7 @@ async function previewArch006(context) {
     };
   }
   const absolutePath = path24.join(context.workspaceRoot, ...contractPath.split("/"));
-  const exists = await pathExists8(absolutePath);
+  const exists = await pathExists9(absolutePath);
   return {
     filesCreated: exists ? [] : [contractPath],
     filesModified: [],
@@ -224207,7 +224996,7 @@ async function applyArch006(context) {
 }
 async function previewDoc001(context) {
   const filePath = path24.join(context.workspaceRoot, "docs", "adrs", "adr-001-tenant-model.md");
-  const exists = await pathExists8(filePath);
+  const exists = await pathExists9(filePath);
   return {
     filesCreated: exists ? [] : [relative5(filePath, context.workspaceRoot)],
     filesModified: [],
@@ -224240,7 +225029,7 @@ async function applyDoc001(context) {
 }
 async function previewDoc002(context) {
   const filePath = path24.join(context.workspaceRoot, "docs", "adrs", "adr-rbac-model.md");
-  const exists = await pathExists8(filePath);
+  const exists = await pathExists9(filePath);
   return {
     filesCreated: exists ? [] : [relative5(filePath, context.workspaceRoot)],
     filesModified: [],
@@ -224375,7 +225164,7 @@ async function applyDep006(context) {
     "contracts",
     `${parsed.sourceModule}.contract.json`
   );
-  if (!await pathExists8(contractPath)) {
+  if (!await pathExists9(contractPath)) {
     return {
       applied: false,
       filesCreated: [],
@@ -224788,7 +225577,7 @@ var jsxExtensions = /* @__PURE__ */ new Set([".tsx", ".jsx"]);
 function normalizePath4(value) {
   return value.replace(/\\/g, "/").replace(/^\.\/+/u, "").replace(/\/+$/u, "").toLowerCase();
 }
-function pathExists9(targetPath) {
+function pathExists10(targetPath) {
   try {
     fs24.accessSync(targetPath);
     return true;
@@ -224875,7 +225664,7 @@ function hasDependencyPrefix(dependencies, prefixes) {
   return false;
 }
 function hasAnyFile(candidateRoot, filePaths) {
-  return filePaths.some((filePath) => pathExists9(path25.join(candidateRoot, ...filePath.split("/"))));
+  return filePaths.some((filePath) => pathExists10(path25.join(candidateRoot, ...filePath.split("/"))));
 }
 function scanForJsxFiles(candidateRoot) {
   const queue = [{ absolutePath: candidateRoot, depth: 0 }];
@@ -224911,25 +225700,25 @@ function collectCandidateSignals(candidateRoot) {
   const dependencies = collectDependencyNames(packageJsonPath);
   return {
     dependencies,
-    hasNextConfig: pathExists9(path25.join(candidateRoot, "next.config.js")) || pathExists9(path25.join(candidateRoot, "next.config.mjs")) || pathExists9(path25.join(candidateRoot, "next.config.ts")),
-    hasViteConfig: pathExists9(path25.join(candidateRoot, "vite.config.js")) || pathExists9(path25.join(candidateRoot, "vite.config.ts")) || pathExists9(path25.join(candidateRoot, "vite.config.mjs")),
-    hasIndexHtml: pathExists9(path25.join(candidateRoot, "index.html")),
-    hasPublicDir: pathExists9(path25.join(candidateRoot, "public")),
-    hasSrcComponents: pathExists9(path25.join(candidateRoot, "src", "components")),
-    hasSrcPages: pathExists9(path25.join(candidateRoot, "src", "pages")),
-    hasSrcApp: pathExists9(path25.join(candidateRoot, "src", "app")),
+    hasNextConfig: pathExists10(path25.join(candidateRoot, "next.config.js")) || pathExists10(path25.join(candidateRoot, "next.config.mjs")) || pathExists10(path25.join(candidateRoot, "next.config.ts")),
+    hasViteConfig: pathExists10(path25.join(candidateRoot, "vite.config.js")) || pathExists10(path25.join(candidateRoot, "vite.config.ts")) || pathExists10(path25.join(candidateRoot, "vite.config.mjs")),
+    hasIndexHtml: pathExists10(path25.join(candidateRoot, "index.html")),
+    hasPublicDir: pathExists10(path25.join(candidateRoot, "public")),
+    hasSrcComponents: pathExists10(path25.join(candidateRoot, "src", "components")),
+    hasSrcPages: pathExists10(path25.join(candidateRoot, "src", "pages")),
+    hasSrcApp: pathExists10(path25.join(candidateRoot, "src", "app")),
     hasJsxTsconfig: hasJsxEnabled(path25.join(candidateRoot, "tsconfig.json")) || hasJsxEnabled(path25.join(candidateRoot, "jsconfig.json")),
     hasJsxFiles: scanForJsxFiles(candidateRoot),
-    hasRoutesDir: pathExists9(path25.join(candidateRoot, "routes")),
-    hasControllersDir: pathExists9(path25.join(candidateRoot, "controllers")),
-    hasPrismaDir: pathExists9(path25.join(candidateRoot, "prisma")),
-    hasDbDir: pathExists9(path25.join(candidateRoot, "db")),
-    hasMigrationsDir: pathExists9(path25.join(candidateRoot, "migrations")),
-    hasApiDir: pathExists9(path25.join(candidateRoot, "api")),
+    hasRoutesDir: pathExists10(path25.join(candidateRoot, "routes")),
+    hasControllersDir: pathExists10(path25.join(candidateRoot, "controllers")),
+    hasPrismaDir: pathExists10(path25.join(candidateRoot, "prisma")),
+    hasDbDir: pathExists10(path25.join(candidateRoot, "db")),
+    hasMigrationsDir: pathExists10(path25.join(candidateRoot, "migrations")),
+    hasApiDir: pathExists10(path25.join(candidateRoot, "api")),
     hasServerEntrypoint: hasAnyFile(candidateRoot, backendEntrypoints),
     hasOpenApiArtifacts: hasAnyFile(candidateRoot, openApiArtifacts),
     hasWorkerEntrypoint: hasAnyFile(candidateRoot, workerEntrypoints),
-    hasPackageJson: pathExists9(packageJsonPath),
+    hasPackageJson: pathExists10(packageJsonPath),
     hasExportsField: hasExportsField(packageJsonPath),
     hasIndexEntrypoint: hasAnyFile(candidateRoot, indexEntrypoints)
   };
@@ -225098,7 +225887,7 @@ function classifyModuleScope(input2) {
     return "backend";
   }
   const candidateRoots = getCandidateRoots(input2.workspaceRoot, input2.modulePath).filter(
-    (candidate) => pathExists9(candidate)
+    (candidate) => pathExists10(candidate)
   );
   const scores = sumScores(
     candidateRoots.map(
@@ -225121,7 +225910,7 @@ function classifyModuleScope(input2) {
 function normalizePath5(value) {
   return value.replace(/\\/g, "/");
 }
-async function pathExists10(targetPath) {
+async function pathExists11(targetPath) {
   try {
     await import_node_fs24.promises.access(targetPath);
     return true;
@@ -225136,9 +225925,32 @@ async function readTextFileIfExists4(filePath) {
     return void 0;
   }
 }
+var sourceFileExtensions2 = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+  ".py",
+  ".go",
+  ".java",
+  ".kt",
+  ".kts",
+  ".cs",
+  ".php",
+  ".rb",
+  ".vue",
+  ".svelte"
+]);
 function sortUnique3(values) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
+function toSafeContractModuleFileStem2(moduleName) {
+  return normalizePath5(moduleName).split("/").map((segment) => segment.trim()).filter((segment) => segment.length > 0).join(".");
+}
 function getModuleRegistry(contract) {
   const modules = contract?.modules;
   if (!modules || typeof modules !== "object" || Array.isArray(modules)) {
@@ -225149,6 +225961,83 @@ function getModuleRegistry(contract) {
 function normalizePublicEntrypointList(entries) {
   return sortUnique3(entries.map((entry) => normalizePath5(entry.trim())).filter((entry) => entry.length > 0));
 }
+function hasConfiguredPublicEntrypoint(registryEntry) {
+  return Array.isArray(registryEntry?.publicEntrypoints) && registryEntry.publicEntrypoints.some(
+    (entry) => typeof entry === "string" && entry.trim().length > 0
+  );
+}
+async function readPackageJsonIfExists(moduleDirectoryPath) {
+  const content = await readTextFileIfExists4(path26.join(moduleDirectoryPath, "package.json"));
+  if (!content) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(content);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function collectModuleSourceEvidence(directoryPath) {
+  let entries;
+  try {
+    entries = await import_node_fs24.promises.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return { sourceFileCount: 0, hasReadme: false, hasEntrypointFile: false };
+  }
+  let sourceFileCount = 0;
+  let hasReadme = false;
+  let hasEntrypointFile = false;
+  for (const entry of entries) {
+    const fullPath = path26.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      if (["node_modules", "dist", "out", "build", "coverage", ".git"].includes(entry.name)) {
+        continue;
+      }
+      const nested = await collectModuleSourceEvidence(fullPath);
+      sourceFileCount += nested.sourceFileCount;
+      hasReadme ||= nested.hasReadme;
+      hasEntrypointFile ||= nested.hasEntrypointFile;
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const lowerName = entry.name.toLowerCase();
+    if (lowerName === "readme.md" || lowerName === "readme.mdx") {
+      hasReadme = true;
+    }
+    if (/^(index|main|app|extension|cli)\.[cm]?[jt]sx?$/iu.test(entry.name)) {
+      hasEntrypointFile = true;
+    }
+    if (sourceFileExtensions2.has(path26.extname(entry.name).toLowerCase())) {
+      sourceFileCount += 1;
+    }
+  }
+  return { sourceFileCount, hasReadme, hasEntrypointFile };
+}
+function hasKnownBoundaryRole(moduleName) {
+  const normalized = moduleName.toLowerCase();
+  const compact = normalized.replace(/[-_/]/gu, "");
+  const segments = normalized.split(/[/-]/u);
+  return ["adr", "ci", "compliance", "config", "governance", "policy", "validation", "smartinit"].some(
+    (role) => compact.includes(role) || segments.includes(role)
+  );
+}
+async function hasPackageEntrypoint(moduleDirectoryPath) {
+  const packageJson = await readPackageJsonIfExists(moduleDirectoryPath);
+  if (!packageJson) {
+    return false;
+  }
+  return ["main", "module", "browser", "types", "bin", "exports"].some(
+    (field) => packageJson[field] !== void 0
+  );
+}
+async function hasIntentionalIndependentEvidence(args) {
+  const moduleDirectoryPath = path26.join(args.workspaceRoot, ...args.moduleEntry.sourcePath.split("/"));
+  const evidence = await collectModuleSourceEvidence(moduleDirectoryPath);
+  return args.moduleEntry.contractExists || args.moduleEntry.hasPublicEntrypoint === true || evidence.hasReadme || evidence.hasEntrypointFile || await hasPackageEntrypoint(moduleDirectoryPath) || args.hasChildren || args.isLeafChild && evidence.sourceFileCount > 0 || hasKnownBoundaryRole(args.moduleEntry.moduleName) || evidence.sourceFileCount >= 2;
+}
 async function loadModuleContractPublicEntrypoints(workspaceRoot, contractPath) {
   const fullContractPath = path26.join(workspaceRoot, ...contractPath.split("/"));
   const content = await readTextFileIfExists4(fullContractPath);
@@ -225189,7 +226078,7 @@ async function discoverModulesFromArchitectureContract(workspaceRoot, contract,
   const discovered = [];
   const discoveredNames = /* @__PURE__ */ new Set();
   const toContractPath = (moduleName, registryEntry) => normalizePath5(
-    typeof registryEntry?.contract === "string" ? registryEntry.contract : `${contractsRoot}/${moduleName}.contract.json`
+    typeof registryEntry?.contract === "string" ? registryEntry.contract : `${contractsRoot}/${toSafeContractModuleFileStem2(moduleName)}.contract.json`
   );
   const resolveMissingPublicEntrypointAlignment = async (registryEntry, contractPath) => {
     if (!Array.isArray(registryEntry?.publicEntrypoints)) {
@@ -225233,9 +226122,9 @@ async function discoverModulesFromArchitectureContract(workspaceRoot, contract,
       continue;
     }
     const contractPath = normalizePath5(
-      typeof registryEntry.contract === "string" ? registryEntry.contract : `${contractsRoot}/${moduleName}.contract.json`
+      typeof registryEntry.contract === "string" ? registryEntry.contract : `${contractsRoot}/${toSafeContractModuleFileStem2(moduleName)}.contract.json`
     );
-    const contractExists = await pathExists10(path26.join(workspaceRoot, ...contractPath.split("/")));
+    const contractExists = await pathExists11(path26.join(workspaceRoot, ...contractPath.split("/")));
     const missingPublicEntrypointAlignment = await resolveMissingPublicEntrypointAlignment(
       registryEntry,
       contractPath
@@ -225248,6 +226137,7 @@ async function discoverModulesFromArchitectureContract(workspaceRoot, contract,
       ...resolveModuleScopeForPath(workspaceRoot, normalizedSourcePath, contract) ? { scope: resolveModuleScopeForPath(workspaceRoot, normalizedSourcePath, contract) } : {},
       contractPath,
       contractExists,
+      hasPublicEntrypoint: hasConfiguredPublicEntrypoint(registryEntry),
       ...missingPublicEntrypointAlignment !== void 0 ? { missingPublicEntrypointAlignment } : {}
     });
     discoveredNames.add(moduleName);
@@ -225259,7 +226149,7 @@ async function discoverModulesFromArchitectureContract(workspaceRoot, contract,
     const registryEntry = moduleRegistry[moduleName];
     const sourcePath = normalizePath5(registryEntry?.path ?? `${normalizedModulesRoot}/${moduleName}`);
     const contractPath = toContractPath(moduleName, registryEntry);
-    const contractExists = await pathExists10(path26.join(workspaceRoot, ...contractPath.split("/")));
+    const contractExists = await pathExists11(path26.join(workspaceRoot, ...contractPath.split("/")));
     const missingPublicEntrypointAlignment = await resolveMissingPublicEntrypointAlignment(
       registryEntry,
       contractPath
@@ -225272,18 +226162,56 @@ async function discoverModulesFromArchitectureContract(workspaceRoot, contract,
       ...resolveModuleScopeForPath(workspaceRoot, sourcePath, contract) ? { scope: resolveModuleScopeForPath(workspaceRoot, sourcePath, contract) } : {},
       contractPath,
       contractExists,
+      hasPublicEntrypoint: hasConfiguredPublicEntrypoint(registryEntry),
       ...missingPublicEntrypointAlignment !== void 0 ? { missingPublicEntrypointAlignment } : {}
     });
     discoveredNames.add(moduleName);
   }
+  for (const moduleRoot of await discoverHierarchicalModuleRoots(workspaceRoot, normalizedModulesRoot)) {
+    if (discoveredNames.has(moduleRoot.moduleId)) {
+      continue;
+    }
+    const registryEntry = moduleRegistry[moduleRoot.moduleId];
+    const contractPath = toContractPath(moduleRoot.moduleId, registryEntry);
+    const contractExists = await pathExists11(path26.join(workspaceRoot, ...contractPath.split("/")));
+    const missingPublicEntrypointAlignment = await resolveMissingPublicEntrypointAlignment(
+      registryEntry,
+      contractPath
+    );
+    discovered.push({
+      moduleName: moduleRoot.moduleId,
+      sourcePath: moduleRoot.sourcePath,
+      discoverySource: "architecture.json",
+      sourcePathExists: true,
+      ...resolveModuleScopeForPath(workspaceRoot, moduleRoot.sourcePath, contract) ? { scope: resolveModuleScopeForPath(workspaceRoot, moduleRoot.sourcePath, contract) } : {},
+      contractPath,
+      contractExists,
+      hasPublicEntrypoint: hasConfiguredPublicEntrypoint(registryEntry),
+      ...missingPublicEntrypointAlignment !== void 0 ? { missingPublicEntrypointAlignment } : {}
+    });
+    discoveredNames.add(moduleRoot.moduleId);
+  }
   return discovered.sort((left, right) => left.moduleName.localeCompare(right.moduleName));
 }
 async function discoverModulesFromFallbackScan(workspaceRoot, modulesRoot = "src/modules", contractsRoot = ".archpilot/contracts") {
-  const moduleNames = await listModuleDirectoryNames(workspaceRoot, modulesRoot);
+  const hierarchicalModules = await discoverHierarchicalModuleRoots(workspaceRoot, modulesRoot);
+  const moduleNames = hierarchicalModules.length > 0 ? [] : await listModuleDirectoryNames(workspaceRoot, modulesRoot);
   const discovered = [];
+  for (const moduleRoot of hierarchicalModules) {
+    const contractPath = `${contractsRoot}/${toSafeContractModuleFileStem2(moduleRoot.moduleId)}.contract.json`;
+    discovered.push({
+      moduleName: moduleRoot.moduleId,
+      sourcePath: moduleRoot.sourcePath,
+      discoverySource: "inferred-scan",
+      sourcePathExists: true,
+      ...resolveModuleScopeForPath(workspaceRoot, moduleRoot.sourcePath) ? { scope: resolveModuleScopeForPath(workspaceRoot, moduleRoot.sourcePath) } : {},
+      contractPath,
+      contractExists: await pathExists11(path26.join(workspaceRoot, ...contractPath.split("/")))
+    });
+  }
   for (const moduleName of moduleNames) {
     const sourcePath = `${modulesRoot}/${moduleName}`;
-    const contractPath = `${contractsRoot}/${moduleName}.contract.json`;
+    const contractPath = `${contractsRoot}/${toSafeContractModuleFileStem2(moduleName)}.contract.json`;
     discovered.push({
       moduleName,
       sourcePath,
@@ -225291,7 +226219,7 @@ async function discoverModulesFromFallbackScan(workspaceRoot, modulesRoot = "src
       sourcePathExists: true,
       ...resolveModuleScopeForPath(workspaceRoot, sourcePath) ? { scope: resolveModuleScopeForPath(workspaceRoot, sourcePath) } : {},
       contractPath,
-      contractExists: await pathExists10(path26.join(workspaceRoot, ...contractPath.split("/")))
+      contractExists: await pathExists11(path26.join(workspaceRoot, ...contractPath.split("/")))
     });
   }
   return discovered;
@@ -225381,14 +226309,39 @@ async function generateArchitectureMap(workspaceRoot, options) {
     moduleFilter: moduleIds
   });
   const edges = dependencySnapshot.edges.map((edge) => toArchitectureMapEdge(edge));
+  const hierarchyEdges = dependencySnapshot.hierarchyEdges;
   const parsedCycles = dependencySnapshot.cycles.map((cycle) => parseCycleString(cycle)).filter((cycle) => cycle.length > 1).sort((left, right) => left.join("->").localeCompare(right.join("->")));
   const incomingMap = buildIncomingMap(modules, edges);
   const outgoingMap = buildOutgoingMap(modules, edges);
   const cycleMembership = new Set(parsedCycles.flatMap((cycle) => cycle));
-  const hotspotSummary = modules.map((moduleEntry) => {
+  const hierarchyParentByChild = new Map(
+    hierarchyEdges.map((edge) => [edge.childModule, edge.parentModule])
+  );
+  const childModulesByParent = /* @__PURE__ */ new Map();
+  for (const edge of hierarchyEdges) {
+    const children = childModulesByParent.get(edge.parentModule) ?? [];
+    children.push(edge.childModule);
+    childModulesByParent.set(edge.parentModule, children);
+  }
+  const independentModuleNames = [];
+  const potentialOrphanModuleNames = [];
+  const hotspotSummary = await Promise.all(modules.map(async (moduleEntry) => {
     const incomingDependencyCount = incomingMap.get(moduleEntry.moduleName)?.length ?? 0;
     const outgoingDependencyCount = outgoingMap.get(moduleEntry.moduleName)?.length ?? 0;
-    const orphan = incomingDependencyCount === 0 && outgoingDependencyCount === 0;
+    const hasNoPeerUsage = incomingDependencyCount === 0 && outgoingDependencyCount === 0;
+    const hasIntentionalEvidence = hasNoPeerUsage ? await hasIntentionalIndependentEvidence({
+      workspaceRoot,
+      moduleEntry,
+      hasChildren: (childModulesByParent.get(moduleEntry.moduleName)?.length ?? 0) > 0,
+      isLeafChild: hierarchyParentByChild.has(moduleEntry.moduleName) && (childModulesByParent.get(moduleEntry.moduleName)?.length ?? 0) === 0
+    }) : false;
+    const orphan = hasNoPeerUsage && !hasIntentionalEvidence;
+    if (hasNoPeerUsage && hasIntentionalEvidence) {
+      independentModuleNames.push(moduleEntry.moduleName);
+    }
+    if (orphan) {
+      potentialOrphanModuleNames.push(moduleEntry.moduleName);
+    }
     return {
       moduleName: moduleEntry.moduleName,
       incomingDependencyCount,
@@ -225400,7 +226353,7 @@ async function generateArchitectureMap(workspaceRoot, options) {
         missingPublicEntrypointAlignment: moduleEntry.missingPublicEntrypointAlignment
       } : {}
     };
-  });
+  }));
   const mostDependedOnModules = sortRankedCounts(
     hotspotSummary.filter((entry) => entry.incomingDependencyCount > 0).map((entry) => ({
       moduleName: entry.moduleName,
@@ -225416,9 +226369,9 @@ async function generateArchitectureMap(workspaceRoot, options) {
   const modulesInCircularDependencies = sortUnique3(
     hotspotSummary.filter((entry) => entry.participatesInCycle).map((entry) => entry.moduleName)
   );
-  const orphanModules = sortUnique3(
-    hotspotSummary.filter((entry) => entry.orphan).map((entry) => entry.moduleName)
-  );
+  const independentModules = sortUnique3(independentModuleNames);
+  const potentialOrphanModules = sortUnique3(potentialOrphanModuleNames);
+  const orphanModules = potentialOrphanModules;
   const missingContracts = sortUnique3(
     hotspotSummary.filter((entry) => entry.missingContract).map((entry) => entry.moduleName)
   );
@@ -225441,11 +226394,14 @@ async function generateArchitectureMap(workspaceRoot, options) {
     modules,
     moduleHotspotSummary: hotspotSummary,
     edges,
+    hierarchyEdges,
     cycles: parsedCycles,
     hotspots: {
       mostDependedOnModules,
       highestOutgoingFanOutModules,
       modulesInCircularDependencies,
+      independentModules,
+      potentialOrphanModules,
       orphanModules,
       missingContracts,
       highlyConnectedModules,
@@ -225455,6 +226411,8 @@ async function generateArchitectureMap(workspaceRoot, options) {
       moduleCount: modules.length,
       edgeCount: edges.length,
       cycleCount: parsedCycles.length,
+      independentCount: independentModules.length,
+      potentialOrphanCount: potentialOrphanModules.length,
       orphanCount: orphanModules.length,
       highlyConnectedCount: highlyConnectedModules.length,
       missingContractCount: missingContracts.length
@@ -225470,6 +226428,11 @@ async function generateArchitectureMap(workspaceRoot, options) {
         importCount: edge.importCount,
         publicImportCount: edge.publicImportCount,
         nonPublicImportCount: edge.nonPublicImportCount
+      })),
+      hierarchyEdges: hierarchyEdges.map((edge) => ({
+        source: edge.parentModule,
+        target: edge.childModule,
+        relationship: "contains"
       }))
     },
     notes: {
@@ -227018,7 +227981,7 @@ async function runGithubPrCommentAdapter(workspaceRoot) {
 // ../core/src/generateOnboardingDocs.ts
 var path31 = __toESM(require("node:path"));
 var import_node_fs29 = require("node:fs");
-async function pathExists11(filePath) {
+async function pathExists12(filePath) {
   try {
     await import_node_fs29.promises.access(filePath);
     return true;
@@ -227072,10 +228035,10 @@ async function generateOnboardingDocs(workspaceRoot) {
     [...map.modules].sort((left, right) => left.moduleName.localeCompare(right.moduleName)).map(async (moduleEntry) => {
       const readmePath = `${moduleEntry.sourcePath}/README.md`;
       const indexPath = `${moduleEntry.sourcePath}/index.ts`;
-      const readmeExists = await pathExists11(
+      const readmeExists = await pathExists12(
         path31.join(workspaceRoot, ...readmePath.split("/"))
       );
-      const indexExists = await pathExists11(
+      const indexExists = await pathExists12(
         path31.join(workspaceRoot, ...indexPath.split("/"))
       );
       const hotspot = hotspotByModule.get(moduleEntry.moduleName);
@@ -227857,7 +228820,7 @@ function normalizePath9(value) {
 function sortUnique10(values) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
-async function pathExists12(targetPath) {
+async function pathExists13(targetPath) {
   try {
     await import_node_fs30.promises.access(targetPath);
     return true;
@@ -228102,18 +229065,18 @@ async function generateImpactAnalysis(workspaceRoot, target, options) {
     const contractPath = moduleEntry.contractPath;
     suggestedFilesToInspect.push({
       path: readmePath,
-      exists: await pathExists12(path32.join(workspaceRoot, ...readmePath.split("/"))),
+      exists: await pathExists13(path32.join(workspaceRoot, ...readmePath.split("/"))),
       kind: "readme"
     });
     suggestedFilesToInspect.push({
       path: indexPath,
-      exists: await pathExists12(path32.join(workspaceRoot, ...indexPath.split("/"))),
+      exists: await pathExists13(path32.join(workspaceRoot, ...indexPath.split("/"))),
       kind: "entrypoint"
     });
     if (contractPath) {
       suggestedFilesToInspect.push({
         path: contractPath,
-        exists: await pathExists12(path32.join(workspaceRoot, ...contractPath.split("/"))),
+        exists: await pathExists13(path32.join(workspaceRoot, ...contractPath.split("/"))),
         kind: "contract"
       });
     }
@@ -230436,7 +231399,7 @@ async function applyQuickFixPlan(workspaceRoot, plan) {
         continue;
       }
       const absoluteTargetPath = path43.resolve(workspaceRoot, action.targetPath);
-      if (await pathExists8(absoluteTargetPath)) {
+      if (await pathExists9(absoluteTargetPath)) {
         skippedExists.push(action.targetPath);
         continue;
       }
@@ -230489,7 +231452,7 @@ function normalizePath11(value) {
 function toAbsolutePath(workspaceRoot, relativePath) {
   return path44.join(workspaceRoot, ...relativePath.split("/"));
 }
-async function pathExists13(targetPath) {
+async function pathExists14(targetPath) {
   try {
     await import_node_fs39.promises.access(targetPath);
     return true;
@@ -230500,6 +231463,9 @@ async function pathExists13(targetPath) {
 function sortUnique12(values) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
+function toSafeContractModuleFileStem3(moduleName) {
+  return normalizePath11(moduleName).split("/").map((segment) => segment.trim()).filter((segment) => segment.length > 0).join(".");
+}
 function wildcardToRegex(pattern) {
   const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
   return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`, "u");
@@ -230515,7 +231481,7 @@ async function inferModulePublicEntrypoints(workspaceRoot, moduleSourcePath, ada
   const normalizedSourcePath = normalizePath11(moduleSourcePath);
   if (/\.[a-z0-9]+$/iu.test(normalizedSourcePath)) {
     const absoluteSourcePath = toAbsolutePath(workspaceRoot, normalizedSourcePath);
-    if (await pathExists13(absoluteSourcePath)) {
+    if (await pathExists14(absoluteSourcePath)) {
       return [normalizedSourcePath];
     }
   }
@@ -230542,14 +231508,14 @@ async function inferModulePublicEntrypoints(workspaceRoot, moduleSourcePath, ada
   const inferred = [];
   for (const fileName of orderedCandidates) {
     const candidateRelative = `${normalizedSourcePath}/${fileName}`;
-    if (await pathExists13(toAbsolutePath(workspaceRoot, candidateRelative))) {
+    if (await pathExists14(toAbsolutePath(workspaceRoot, candidateRelative))) {
       inferred.push(candidateRelative);
       break;
     }
   }
   for (const publicDirName of adapter.publicEntrypointDirectoryNames) {
     const publicDirectoryRelative = `${normalizedSourcePath}/${publicDirName}`;
-    if (await pathExists13(toAbsolutePath(workspaceRoot, publicDirectoryRelative))) {
+    if (await pathExists14(toAbsolutePath(workspaceRoot, publicDirectoryRelative))) {
       inferred.push(publicDirectoryRelative);
       break;
     }
@@ -230581,7 +231547,10 @@ function resolveContractPath(contract, moduleName) {
     return normalizePath11(configured);
   }
   return normalizePath11(
-    path44.posix.join(resolveContractsRootFromContract(contract), `${moduleName}.contract.json`)
+    path44.posix.join(
+      resolveContractsRootFromContract(contract),
+      `${toSafeContractModuleFileStem3(moduleName)}.contract.json`
+    )
   );
 }
 function createModuleContract(input2) {
@@ -230593,6 +231562,23 @@ function createModuleContract(input2) {
     exposedApis: []
   };
 }
+async function readExistingModuleContractPublicEntrypoints(workspaceRoot, contractPath) {
+  try {
+    const raw = await import_node_fs39.promises.readFile(toAbsolutePath(workspaceRoot, contractPath), {
+      encoding: "utf8"
+    });
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.publicEntrypoints)) {
+      return void 0;
+    }
+    if (parsed.publicEntrypoints.some((entry) => typeof entry !== "string")) {
+      return void 0;
+    }
+    return sortUnique12(parsed.publicEntrypoints.map((entry) => normalizePath11(entry)));
+  } catch {
+    return void 0;
+  }
+}
 function isRegistryEntryDifferent(input2) {
   const moduleRegistry = getModuleRegistry2(input2.contract);
   const existing = moduleRegistry[input2.moduleName] ?? {};
@@ -230619,7 +231605,15 @@ async function generateMissingModuleContracts(workspaceRoot) {
   )) {
     const contractPath = resolveContractPath(contract, moduleEntry.moduleName);
     const sourcePath = normalizePath11(moduleEntry.sourcePath);
-    const publicEntrypoints = await inferModulePublicEntrypoints(
+    const absoluteContractPath = toAbsolutePath(workspaceRoot, contractPath);
+    const contractExists = await pathExists14(absoluteContractPath);
+    const existingContractPublicEntrypoints = contractExists ? await readExistingModuleContractPublicEntrypoints(workspaceRoot, contractPath) : void 0;
+    const configuredPublicEntrypoints = !contractExists && Array.isArray(getModuleRegistry2(contract)[moduleEntry.moduleName]?.publicEntrypoints) ? sortUnique12(
+      getModuleRegistry2(contract)[moduleEntry.moduleName]?.publicEntrypoints?.map(
+        (entry) => normalizePath11(entry)
+      ) ?? []
+    ) : void 0;
+    const publicEntrypoints = existingContractPublicEntrypoints ?? configuredPublicEntrypoints ?? await inferModulePublicEntrypoints(
       workspaceRoot,
       sourcePath,
       adapter
@@ -230629,8 +231623,7 @@ async function generateMissingModuleContracts(workspaceRoot) {
       dependsOn: dependsOnBySource.get(moduleEntry.moduleName) ?? [],
       publicEntrypoints
     });
-    const absoluteContractPath = toAbsolutePath(workspaceRoot, contractPath);
-    if (await pathExists13(absoluteContractPath)) {
+    if (contractExists) {
       skippedExistingContracts.push(contractPath);
     } else {
       await import_node_fs39.promises.mkdir(path44.dirname(absoluteContractPath), { recursive: true });
@@ -230676,7 +231669,7 @@ function normalizePath12(value) {
 function toAbsolutePath2(workspaceRoot, relativePath) {
   return path45.join(workspaceRoot, ...relativePath.split("/"));
 }
-async function pathExists14(targetPath) {
+async function pathExists15(targetPath) {
   try {
     await import_node_fs40.promises.access(targetPath);
     return true;
@@ -230739,7 +231732,7 @@ async function bootstrapArchitectureConfig(workspaceRoot, options) {
   ensuredDirectories.push(".archpilot", ".archpilot/contracts");
   const dependencyRulesPath = ".archpilot/dependency-rules.json";
   const dependencyRulesAbsolutePath = toAbsolutePath2(workspaceRoot, dependencyRulesPath);
-  if (await pathExists14(dependencyRulesAbsolutePath)) {
+  if (await pathExists15(dependencyRulesAbsolutePath)) {
     skippedExistingFiles.push(dependencyRulesPath);
   } else {
     await import_node_fs40.promises.writeFile(
@@ -230751,7 +231744,7 @@ async function bootstrapArchitectureConfig(workspaceRoot, options) {
   }
   const layerRulesPath = ".archpilot/layer-rules.json";
   const layerRulesAbsolutePath = toAbsolutePath2(workspaceRoot, layerRulesPath);
-  if (await pathExists14(layerRulesAbsolutePath)) {
+  if (await pathExists15(layerRulesAbsolutePath)) {
     skippedExistingFiles.push(layerRulesPath);
   } else {
     await import_node_fs40.promises.writeFile(layerRulesAbsolutePath, renderLayerRulesConfig(modules), {
@@ -232776,7 +233769,7 @@ var appRouteReservedDirectoryNames = /* @__PURE__ */ new Set([
   "common",
   "shared-ui"
 ]);
-var sourceFileExtensions = /* @__PURE__ */ new Set([
+var sourceFileExtensions3 = /* @__PURE__ */ new Set([
   ".ts",
   ".tsx",
   ".js",
@@ -232830,7 +233823,7 @@ function safeReadDirEntries(directoryPath) {
     return [];
   }
 }
-function pathExists15(pathValue) {
+function pathExists16(pathValue) {
   try {
     fs48.accessSync(pathValue);
     return true;
@@ -232894,7 +233887,7 @@ function inspectModuleFolder(absolutePath) {
         continue;
       }
       const extension = path53.extname(entry.name).toLowerCase();
-      if (sourceFileExtensions.has(extension)) {
+      if (sourceFileExtensions3.has(extension)) {
         hasSourceFiles = true;
         sourceFileCount += 1;
       }
@@ -232974,14 +233967,17 @@ function collectModuleCandidatesFromRoot(workspaceRoot, modulesRootRelative, def
     if (skipFrontendUtilities && frontendUtilityDirectoryNames.has(entry.name.toLowerCase())) {
       continue;
     }
-    const moduleName = entry.name;
-    const moduleRelativePath = normalizePath13(`${modulesRootRelative}/${moduleName}`);
+    const rootSegments = modulesRootRelative.split("/").filter((segment) => segment.length > 0);
+    const sourceIndex = rootSegments.lastIndexOf("src");
+    const rootLeaf = rootSegments[rootSegments.length - 1]?.toLowerCase();
+    const parentName = sourceIndex > 0 && (rootLeaf === "src" || ["modules", "features"].includes(rootLeaf ?? "")) ? rootSegments[sourceIndex - 1] : void 0;
+    const moduleName = parentName && parentName !== "src" ? `${parentName}/${entry.name}` : ["domain", "domains", "application", "infrastructure"].includes(rootLeaf ?? "") ? `${rootSegments[rootSegments.length - 1]}/${entry.name}` : entry.name;
     const moduleAbsolutePath = path53.join(absoluteRoot, entry.name);
     const inspected = inspectModuleFolder(moduleAbsolutePath);
     const detected = makeDetectedModule(
       workspaceRoot,
       moduleName,
-      moduleRelativePath,
+      normalizePath13(`${modulesRootRelative}/${entry.name}`),
       modulesRootRelative,
       inspected.hasSourceFiles,
       inspected.hasRoleFiles,
@@ -233042,6 +234038,10 @@ function collectExplicitRoots(workspaceRoot) {
   for (const root of [
     "src/modules",
     "src/features",
+    "src/domain",
+    "src/domains",
+    "src/application",
+    "src/infrastructure",
     "src/app",
     "app",
     "backend/src/modules",
@@ -233058,7 +234058,7 @@ function collectExplicitRoots(workspaceRoot) {
     "packages",
     "libs"
   ]) {
-    if (pathExists15(path53.join(workspaceRoot, ...root.split("/")))) {
+    if (pathExists16(path53.join(workspaceRoot, ...root.split("/")))) {
       roots.push(root);
     }
   }
@@ -233068,23 +234068,49 @@ function collectExplicitRoots(workspaceRoot) {
       continue;
     }
     for (const candidate of [
+      `apps/${appEntry.name}/src`,
       `apps/${appEntry.name}/src/modules`,
       `apps/${appEntry.name}/src/features`,
+      `apps/${appEntry.name}/src/domain`,
+      `apps/${appEntry.name}/src/domains`,
+      `apps/${appEntry.name}/src/application`,
+      `apps/${appEntry.name}/src/infrastructure`,
       `apps/${appEntry.name}/app`,
       `apps/${appEntry.name}/src/app`
     ]) {
-      if (pathExists15(path53.join(workspaceRoot, ...candidate.split("/")))) {
+      if (pathExists16(path53.join(workspaceRoot, ...candidate.split("/")))) {
         roots.push(candidate);
       }
     }
   }
+  for (const container of ["packages", "services"]) {
+    const containerRoot = path53.join(workspaceRoot, container);
+    for (const containerEntry of safeReadDirEntries(containerRoot)) {
+      if (!containerEntry.isDirectory() || ignoredDirectoryNames4.has(containerEntry.name)) {
+        continue;
+      }
+      for (const candidate of [
+        `${container}/${containerEntry.name}/src`,
+        `${container}/${containerEntry.name}/src/modules`,
+        `${container}/${containerEntry.name}/src/features`,
+        `${container}/${containerEntry.name}/src/domain`,
+        `${container}/${containerEntry.name}/src/domains`,
+        `${container}/${containerEntry.name}/src/application`,
+        `${container}/${containerEntry.name}/src/infrastructure`
+      ]) {
+        if (pathExists16(path53.join(workspaceRoot, ...candidate.split("/")))) {
+          roots.push(candidate);
+        }
+      }
+    }
+  }
   return uniqueSorted(roots);
 }
 function collectJavaPackageRoots(workspaceRoot) {
   const roots = [];
   for (const sourceRoot of ["src/main/java", "src/main/kotlin", "src"]) {
     const absoluteSourceRoot = path53.join(workspaceRoot, ...sourceRoot.split("/"));
-    if (!pathExists15(absoluteSourceRoot)) {
+    if (!pathExists16(absoluteSourceRoot)) {
       continue;
     }
     const queue = [
@@ -233891,7 +234917,7 @@ function safeReadText3(filePath, maxChars = 3e4) {
     return void 0;
   }
 }
-function pathExists16(pathValue) {
+function pathExists17(pathValue) {
   try {
     fs51.accessSync(pathValue);
     return true;
@@ -233997,7 +235023,7 @@ function collectCandidateRoots(workspaceRoot, topology) {
     }
   }
   for (const root of ["backend", "frontend"]) {
-    if (pathExists16(path56.join(workspaceRoot, root))) {
+    if (pathExists17(path56.join(workspaceRoot, root))) {
       roots.add(root);
     }
   }