@archpilotlabs/archpilot 0.0.9 → 0.0.10

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();
@@ -215027,6 +215340,37 @@ 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(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 });
+  }
+  return aliases.sort((left, right) => {
+    const lengthCompare = right.packageName.length - left.packageName.length;
+    if (lengthCompare !== 0) {
+      return lengthCompare;
+    }
+    return left.packageName.localeCompare(right.packageName);
+  });
+}
 function validateDependencyModuleRules(moduleName, value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new DependencyRulesConfigError(
@@ -215500,7 +215844,32 @@ 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)
+  })).find(
+    (candidate) => candidate.remainder !== void 0
+  );
+  if (!packageAlias) {
+    return void 0;
+  }
+  const { alias, remainder } = packageAlias;
+  if (remainder.length === 0) {
+    return resolveImportPath(alias.moduleRoot, 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 +215924,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 +215948,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,7 +215962,11 @@ 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}`
   );
@@ -215599,7 +215979,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 +215988,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 +216014,7 @@ async function collectCrossModuleImports(workspaceRoot, modulesRootRelativePath,
           modulesRootRelativePath,
           moduleRoots,
           explicitStandaloneModuleByPath,
+          workspacePackageAliases,
           sourceFilePath,
           importReference.specifier,
           adapter
@@ -215776,7 +216160,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);
@@ -215923,6 +216307,7 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
     workspaceRoot,
     architectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(moduleRoots);
   const moduleIds = sortUnique2([...moduleRoots.keys(), ...explicitStandaloneModuleByPath.values()]);
   const registeredModuleIds = new Set(moduleIds);
   const imports = await collectCrossModuleImports(
@@ -215930,9 +216315,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 +216337,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 +216349,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 +216367,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 +216376,8 @@ async function buildDependencyGraphSummary(workspaceRoot, architectureContract,
         unusedDeclaredDependencies,
         undeclaredActualDependencies
       };
-    })
+    }),
+    hierarchyEdges
   };
 }
 async function validateDependencyContractBoundaries(workspaceRoot, architectureContract, options) {
@@ -215996,19 +216391,22 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
     workspaceRoot,
     architectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(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,
@@ -216080,7 +216478,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 +216503,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,
@@ -216172,17 +216570,18 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
         }
         continue;
       }
-      if (targetContract.contract.publicEntrypoints.length > 0 && normalizePath2(dependencyImport.resolvedTargetRelativePath) !== buildModuleIndexEntrypointPath(
-        modulesRoot,
-        dependencyImport.targetModule,
-        adapter
+      if (targetContract.contract.publicEntrypoints.length > 0 && !isImportWithinPublicEntrypoints(
+        dependencyImport.resolvedTargetRelativePath,
+        targetContract.contract.publicEntrypoints
       )) {
+        const expectedEntrypoint = targetContract.contract.publicEntrypoints[0] ?? buildModuleIndexEntrypointPath(modulesRoot, dependencyImport.targetModule, adapter);
+        const publicEntrypointLabel = expectedEntrypoint.endsWith("/index.ts") ? "index.ts public entrypoint" : "public entrypoint";
         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)}.`,
+            `Module '${dependencyImport.sourceModule}' must import module '${dependencyImport.targetModule}' via its ${publicEntrypointLabel}: ${expectedEntrypoint}.`,
             {
               findingType: "module-dependency",
               module: dependencyImport.sourceModule,
@@ -216223,7 +216622,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 +216651,7 @@ async function validateDependencyContractBoundaries(workspaceRoot, architectureC
       ...explicitStandaloneModuleByPath.values()
     ]);
     const importedBySource = buildActualImportedModuleSetBySource(
-      imports,
+      peerImports,
       registeredModuleIds
     );
     for (const moduleName of [...registeredModuleIds].sort(
@@ -216267,7 +216666,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;
       }
@@ -216322,13 +216723,16 @@ async function validateDependencyBoundaries(workspaceRoot, options) {
     workspaceRoot,
     parsedArchitectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(moduleRoots);
   const imports = await collectCrossModuleImports(
     workspaceRoot,
     modulesRootRelativePath,
     moduleRoots,
     explicitStandaloneModuleByPath,
+    workspacePackageAliases,
     adapter
   );
+  const peerImports = filterPeerModuleImports(imports);
   const findings = [];
   let dependencyRules;
   let dependencyRulesSkipReason;
@@ -216349,7 +216753,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 +216785,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;
@@ -216433,7 +216837,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;
       });
@@ -216481,6 +216885,7 @@ async function buildModuleDependencyGraphSnapshot(workspaceRoot, options) {
     workspaceRoot,
     parsedArchitectureContract
   );
+  const workspacePackageAliases = await buildWorkspacePackageAliasMap(moduleRoots);
   const discoveredModules = sortUnique2([
     ...moduleRoots.keys(),
     ...explicitStandaloneModuleByPath.values()
@@ -216493,9 +216898,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 +216954,7 @@ async function buildModuleDependencyGraphSnapshot(workspaceRoot, options) {
   return {
     modules,
     edges,
+    hierarchyEdges: buildModuleHierarchyEdges(modules),
     cycles,
     imports
   };
@@ -219949,11 +220356,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,
@@ -221172,8 +221579,17 @@ 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));
+      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,8 +221597,9 @@ 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);
+      for (const moduleDirectory of moduleDirectories2) {
+        const moduleName = moduleDirectory.moduleName;
+        const moduleDir = path21.join(workspaceRoot, ...moduleDirectory.sourcePath.split("/"));
         const readmeExists = await pathExists7(path21.join(moduleDir, "README.md"));
         const indexExists = await pathExists7(path21.join(moduleDir, "index.ts"));
         const registryPublicEntrypoints = (contract.modules[moduleName]?.publicEntrypoints ?? []).filter((entry) => typeof entry === "string").map((entry) => normalizeEntrypoint(entry));
@@ -221311,18 +221728,111 @@ 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;
@@ -221336,11 +221846,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 +221866,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 +222648,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) {
@@ -225136,9 +225652,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 +225688,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 +225805,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,7 +225849,7 @@ 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 missingPublicEntrypointAlignment = await resolveMissingPublicEntrypointAlignment(
@@ -225248,6 +225864,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);
@@ -225272,18 +225889,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 pathExists10(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 pathExists10(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,
@@ -225381,14 +226036,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 +226080,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 +226096,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 +226121,14 @@ async function generateArchitectureMap(workspaceRoot, options) {
     modules,
     moduleHotspotSummary: hotspotSummary,
     edges,
+    hierarchyEdges,
     cycles: parsedCycles,
     hotspots: {
       mostDependedOnModules,
       highestOutgoingFanOutModules,
       modulesInCircularDependencies,
+      independentModules,
+      potentialOrphanModules,
       orphanModules,
       missingContracts,
       highlyConnectedModules,
@@ -225455,6 +226138,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 +226155,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: {
@@ -230500,6 +231190,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");
@@ -230581,7 +231274,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 +231289,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 +231332,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 pathExists13(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 +231350,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 });
@@ -232776,7 +233496,7 @@ var appRouteReservedDirectoryNames = /* @__PURE__ */ new Set([
   "common",
   "shared-ui"
 ]);
-var sourceFileExtensions = /* @__PURE__ */ new Set([
+var sourceFileExtensions3 = /* @__PURE__ */ new Set([
   ".ts",
   ".tsx",
   ".js",
@@ -232894,7 +233614,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 +233694,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 +233765,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",
@@ -233068,8 +233795,13 @@ 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`
     ]) {
@@ -233078,6 +233810,27 @@ function collectExplicitRoots(workspaceRoot) {
       }
     }
   }
+  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 (pathExists15(path53.join(workspaceRoot, ...candidate.split("/")))) {
+          roots.push(candidate);
+        }
+      }
+    }
+  }
   return uniqueSorted(roots);
 }
 function collectJavaPackageRoots(workspaceRoot) {