@harness-engineering/core 0.6.0 → 0.8.0

package/dist/index.mjs

@@ -18,17 +18,17 @@ import { promisify } from "util";
 import { glob } from "glob";
 var accessAsync = promisify(access);
 var readFileAsync = promisify(readFile);
-async function fileExists(path2) {
+async function fileExists(path3) {
   try {
-    await accessAsync(path2, constants.F_OK);
+    await accessAsync(path3, constants.F_OK);
     return true;
   } catch {
     return false;
   }
 }
-async function readFileContent(path2) {
+async function readFileContent(path3) {
   try {
-    const content = await readFileAsync(path2, "utf-8");
+    const content = await readFileAsync(path3, "utf-8");
     return Ok(content);
   } catch (error) {
     return Err(error);
@@ -76,15 +76,15 @@ function validateConfig(data, schema) {
   let message = "Configuration validation failed";
   const suggestions = [];
   if (firstError) {
-    const path2 = firstError.path.join(".");
-    const pathDisplay = path2 ? ` at "${path2}"` : "";
+    const path3 = firstError.path.join(".");
+    const pathDisplay = path3 ? ` at "${path3}"` : "";
     if (firstError.code === "invalid_type") {
       const received = firstError.received;
       const expected = firstError.expected;
       if (received === "undefined") {
         code = "MISSING_FIELD";
         message = `Missing required field${pathDisplay}: ${firstError.message}`;
-        suggestions.push(`Field "${path2}" is required and must be of type "${expected}"`);
+        suggestions.push(`Field "${path3}" is required and must be of type "${expected}"`);
       } else {
         code = "INVALID_TYPE";
         message = `Invalid type${pathDisplay}: ${firstError.message}`;
@@ -297,27 +297,30 @@ function extractSections(content) {
     return result;
   });
 }
-function isExternalLink(path2) {
-  return path2.startsWith("http://") || path2.startsWith("https://") || path2.startsWith("#") || path2.startsWith("mailto:");
+function isExternalLink(path3) {
+  return path3.startsWith("http://") || path3.startsWith("https://") || path3.startsWith("#") || path3.startsWith("mailto:");
 }
 function resolveLinkPath(linkPath, baseDir) {
   return linkPath.startsWith(".") ? join(baseDir, linkPath) : linkPath;
 }
-async function validateAgentsMap(path2 = "./AGENTS.md") {
-  const contentResult = await readFileContent(path2);
+async function validateAgentsMap(path3 = "./AGENTS.md") {
+  console.warn(
+    "[harness] validateAgentsMap() is deprecated. Use graph-based validation via Assembler.checkCoverage() from @harness-engineering/graph"
+  );
+  const contentResult = await readFileContent(path3);
   if (!contentResult.ok) {
     return Err(
       createError(
         "PARSE_ERROR",
         `Failed to read AGENTS.md: ${contentResult.error.message}`,
-        { path: path2 },
+        { path: path3 },
         ["Ensure the file exists", "Check file permissions"]
       )
     );
   }
   const content = contentResult.value;
   const sections = extractSections(content);
-  const baseDir = dirname(path2);
+  const baseDir = dirname(path3);
   const sectionTitles = sections.map((s) => s.title);
   const missingSections = REQUIRED_SECTIONS.filter(
     (required) => !sectionTitles.some((title) => title.toLowerCase().includes(required.toLowerCase()))
@@ -379,7 +382,21 @@ function suggestSection(filePath, domain) {
   return `${domain} Reference`;
 }
 async function checkDocCoverage(domain, options = {}) {
-  const { docsDir = "./docs", sourceDir = "./src", excludePatterns = [] } = options;
+  const { docsDir = "./docs", sourceDir = "./src", excludePatterns = [], graphCoverage } = options;
+  if (graphCoverage) {
+    const gaps = graphCoverage.undocumented.map((file) => ({
+      file,
+      suggestedSection: suggestSection(file, domain),
+      importance: determineImportance(file)
+    }));
+    return Ok({
+      domain,
+      documented: graphCoverage.documented,
+      undocumented: graphCoverage.undocumented,
+      coveragePercentage: graphCoverage.coveragePercentage,
+      gaps
+    });
+  }
   try {
     const sourceFiles = await findFiles("**/*.{ts,js,tsx,jsx}", sourceDir);
     const filteredSourceFiles = sourceFiles.filter((file) => {
@@ -445,8 +462,8 @@ async function checkDocCoverage(domain, options = {}) {
 
 // src/context/knowledge-map.ts
 import { join as join2, basename as basename2, relative as relative2 } from "path";
-function suggestFix(path2, existingFiles) {
-  const targetName = basename2(path2).toLowerCase();
+function suggestFix(path3, existingFiles) {
+  const targetName = basename2(path3).toLowerCase();
   const similar = existingFiles.find((file) => {
     const fileName = basename2(file).toLowerCase();
     return fileName.includes(targetName) || targetName.includes(fileName);
@@ -454,9 +471,12 @@ function suggestFix(path2, existingFiles) {
   if (similar) {
     return `Did you mean "${similar}"?`;
   }
-  return `Create the file "${path2}" or remove the link`;
+  return `Create the file "${path3}" or remove the link`;
 }
 async function validateKnowledgeMap(rootDir = process.cwd()) {
+  console.warn(
+    "[harness] validateKnowledgeMap() is deprecated. Use graph-based validation via Assembler.checkCoverage() from @harness-engineering/graph"
+  );
   const agentsPath = join2(rootDir, "AGENTS.md");
   const agentsResult = await validateAgentsMap(agentsPath);
   if (!agentsResult.ok) {
@@ -530,18 +550,9 @@ function matchesExcludePattern(relativePath, excludePatterns) {
     return regex.test(relativePath);
   });
 }
-async function generateAgentsMap(config) {
+async function generateAgentsMap(config, graphSections) {
   const { rootDir, includePaths, excludePaths, sections = DEFAULT_SECTIONS } = config;
   try {
-    const allFiles = [];
-    for (const pattern of includePaths) {
-      const files = await findFiles(pattern, rootDir);
-      allFiles.push(...files);
-    }
-    const filteredFiles = allFiles.filter((file) => {
-      const relativePath = relative3(rootDir, file);
-      return !matchesExcludePattern(relativePath, excludePaths);
-    });
     const lines = [];
     lines.push("# AI Agent Knowledge Map");
     lines.push("");
@@ -551,41 +562,68 @@ async function generateAgentsMap(config) {
     lines.push("");
     lines.push("> Add a brief description of this project, its purpose, and key technologies.");
     lines.push("");
-    lines.push("## Repository Structure");
-    lines.push("");
-    const grouped = groupByDirectory(filteredFiles, rootDir);
-    for (const [dir, files] of grouped) {
-      if (dir !== ".") {
-        lines.push(`### ${dir}/`);
+    if (graphSections) {
+      for (const section of graphSections) {
+        lines.push(`## ${section.name}`);
         lines.push("");
-      }
-      for (const file of files.slice(0, 10)) {
-        lines.push(formatFileLink(file));
-      }
-      if (files.length > 10) {
-        lines.push(`- _... and ${files.length - 10} more files_`);
-      }
-      lines.push("");
-    }
-    for (const section of sections) {
-      lines.push(`## ${section.name}`);
-      lines.push("");
-      if (section.description) {
-        lines.push(section.description);
+        if (section.description) {
+          lines.push(section.description);
+          lines.push("");
+        }
+        for (const file of section.files.slice(0, 20)) {
+          lines.push(formatFileLink(file));
+        }
+        if (section.files.length > 20) {
+          lines.push(`- _... and ${section.files.length - 20} more files_`);
+        }
         lines.push("");
       }
-      const sectionFiles = await findFiles(section.pattern, rootDir);
-      const filteredSectionFiles = sectionFiles.filter((file) => {
+    } else {
+      const allFiles = [];
+      for (const pattern of includePaths) {
+        const files = await findFiles(pattern, rootDir);
+        allFiles.push(...files);
+      }
+      const filteredFiles = allFiles.filter((file) => {
         const relativePath = relative3(rootDir, file);
         return !matchesExcludePattern(relativePath, excludePaths);
       });
-      for (const file of filteredSectionFiles.slice(0, 20)) {
-        lines.push(formatFileLink(relative3(rootDir, file)));
+      lines.push("## Repository Structure");
+      lines.push("");
+      const grouped = groupByDirectory(filteredFiles, rootDir);
+      for (const [dir, files] of grouped) {
+        if (dir !== ".") {
+          lines.push(`### ${dir}/`);
+          lines.push("");
+        }
+        for (const file of files.slice(0, 10)) {
+          lines.push(formatFileLink(file));
+        }
+        if (files.length > 10) {
+          lines.push(`- _... and ${files.length - 10} more files_`);
+        }
+        lines.push("");
       }
-      if (filteredSectionFiles.length > 20) {
-        lines.push(`- _... and ${filteredSectionFiles.length - 20} more files_`);
+      for (const section of sections) {
+        lines.push(`## ${section.name}`);
+        lines.push("");
+        if (section.description) {
+          lines.push(section.description);
+          lines.push("");
+        }
+        const sectionFiles = await findFiles(section.pattern, rootDir);
+        const filteredSectionFiles = sectionFiles.filter((file) => {
+          const relativePath = relative3(rootDir, file);
+          return !matchesExcludePattern(relativePath, excludePaths);
+        });
+        for (const file of filteredSectionFiles.slice(0, 20)) {
+          lines.push(formatFileLink(relative3(rootDir, file)));
+        }
+        if (filteredSectionFiles.length > 20) {
+          lines.push(`- _... and ${filteredSectionFiles.length - 20} more files_`);
+        }
+        lines.push("");
       }
-      lines.push("");
     }
     lines.push("## Development Workflow");
     lines.push("");
@@ -615,7 +653,21 @@ var DEFAULT_RATIOS = {
   interfaces: 0.1,
   reserve: 0.1
 };
-function contextBudget(totalTokens, overrides) {
+var NODE_TYPE_TO_CATEGORY = {
+  file: "activeCode",
+  function: "activeCode",
+  class: "activeCode",
+  method: "activeCode",
+  interface: "interfaces",
+  variable: "interfaces",
+  adr: "projectManifest",
+  document: "projectManifest",
+  spec: "taskSpec",
+  task: "taskSpec",
+  prompt: "systemPrompt",
+  system: "systemPrompt"
+};
+function contextBudget(totalTokens, overrides, graphDensity) {
   const ratios = {
     systemPrompt: DEFAULT_RATIOS.systemPrompt,
     projectManifest: DEFAULT_RATIOS.projectManifest,
@@ -624,6 +676,52 @@ function contextBudget(totalTokens, overrides) {
     interfaces: DEFAULT_RATIOS.interfaces,
     reserve: DEFAULT_RATIOS.reserve
   };
+  if (graphDensity) {
+    const categoryWeights = {
+      systemPrompt: 0,
+      projectManifest: 0,
+      taskSpec: 0,
+      activeCode: 0,
+      interfaces: 0,
+      reserve: 0
+    };
+    for (const [nodeType, count] of Object.entries(graphDensity)) {
+      const category = NODE_TYPE_TO_CATEGORY[nodeType];
+      if (category) {
+        categoryWeights[category] += count;
+      }
+    }
+    const totalWeight = Object.values(categoryWeights).reduce((sum, w) => sum + w, 0);
+    if (totalWeight > 0) {
+      const MIN_ALLOCATION = 0.01;
+      for (const key of Object.keys(ratios)) {
+        if (categoryWeights[key] > 0) {
+          ratios[key] = categoryWeights[key] / totalWeight;
+        } else {
+          ratios[key] = MIN_ALLOCATION;
+        }
+      }
+      if (ratios.reserve < DEFAULT_RATIOS.reserve) {
+        ratios.reserve = DEFAULT_RATIOS.reserve;
+      }
+      if (ratios.systemPrompt < DEFAULT_RATIOS.systemPrompt) {
+        ratios.systemPrompt = DEFAULT_RATIOS.systemPrompt;
+      }
+      const ratioSum = Object.values(ratios).reduce((sum, r) => sum + r, 0);
+      for (const key of Object.keys(ratios)) {
+        ratios[key] = ratios[key] / ratioSum;
+      }
+      for (const key of Object.keys(ratios)) {
+        if (ratios[key] < MIN_ALLOCATION) {
+          ratios[key] = MIN_ALLOCATION;
+        }
+      }
+      const finalSum = Object.values(ratios).reduce((sum, r) => sum + r, 0);
+      for (const key of Object.keys(ratios)) {
+        ratios[key] = ratios[key] / finalSum;
+      }
+    }
+  }
   if (overrides) {
     let overrideSum = 0;
     const overrideKeys = [];
@@ -637,12 +735,12 @@ function contextBudget(totalTokens, overrides) {
     }
     if (overrideKeys.length > 0 && overrideKeys.length < 6) {
       const remaining = 1 - overrideSum;
-      const nonOverridden = Object.keys(DEFAULT_RATIOS).filter(
+      const nonOverridden = Object.keys(ratios).filter(
         (k) => !overrideKeys.includes(k)
       );
-      const originalSum = nonOverridden.reduce((sum, k) => sum + DEFAULT_RATIOS[k], 0);
+      const originalSum = nonOverridden.reduce((sum, k) => sum + ratios[k], 0);
       for (const k of nonOverridden) {
-        ratios[k] = remaining * (DEFAULT_RATIOS[k] / originalSum);
+        ratios[k] = remaining * (ratios[k] / originalSum);
       }
     }
   }
@@ -693,7 +791,7 @@ var PHASE_PRIORITIES = {
     { category: "config", patterns: ["harness.config.json", "package.json"], priority: 5 }
   ]
 };
-function contextFilter(phase, maxCategories) {
+function contextFilter(phase, maxCategories, graphFilePaths) {
   const categories = PHASE_PRIORITIES[phase];
   const limit = maxCategories ?? categories.length;
   const included = categories.slice(0, limit);
@@ -702,7 +800,7 @@ function contextFilter(phase, maxCategories) {
     phase,
     includedCategories: included.map((c) => c.category),
     excludedCategories: excluded.map((c) => c.category),
-    filePatterns: included.flatMap((c) => c.patterns)
+    filePatterns: graphFilePaths ?? included.flatMap((c) => c.patterns)
   };
 }
 function getPhaseCategories(phase) {
@@ -746,7 +844,13 @@ function getImportType(imp) {
   if (imp.kind === "type") return "type-only";
   return "static";
 }
-async function buildDependencyGraph(files, parser) {
+async function buildDependencyGraph(files, parser, graphDependencyData) {
+  if (graphDependencyData) {
+    return Ok({
+      nodes: graphDependencyData.nodes,
+      edges: graphDependencyData.edges
+    });
+  }
   const nodes = [...files];
   const edges = [];
   for (const file of files) {
@@ -796,7 +900,19 @@ function checkLayerViolations(graph, layers, rootDir) {
   return violations;
 }
 async function validateDependencies(config) {
-  const { layers, rootDir, parser, fallbackBehavior = "error" } = config;
+  const { layers, rootDir, parser, fallbackBehavior = "error", graphDependencyData } = config;
+  if (graphDependencyData) {
+    const graphResult2 = await buildDependencyGraph([], parser, graphDependencyData);
+    if (!graphResult2.ok) {
+      return Err(graphResult2.error);
+    }
+    const violations2 = checkLayerViolations(graphResult2.value, layers, rootDir);
+    return Ok({
+      valid: violations2.length === 0,
+      violations: violations2,
+      graph: graphResult2.value
+    });
+  }
   const healthResult = await parser.health();
   if (!healthResult.ok || !healthResult.value.available) {
     if (fallbackBehavior === "skip") {
@@ -930,8 +1046,8 @@ function detectCircularDeps(graph) {
     largestCycle
   });
 }
-async function detectCircularDepsInFiles(files, parser) {
-  const graphResult = await buildDependencyGraph(files, parser);
+async function detectCircularDepsInFiles(files, parser, graphDependencyData) {
+  const graphResult = await buildDependencyGraph(files, parser, graphDependencyData);
   if (!graphResult.ok) {
     return graphResult;
   }
@@ -949,8 +1065,8 @@ function createBoundaryValidator(schema, name) {
         return Ok(result.data);
       }
       const suggestions = result.error.issues.map((issue) => {
-        const path2 = issue.path.join(".");
-        return path2 ? `${path2}: ${issue.message}` : issue.message;
+        const path3 = issue.path.join(".");
+        return path3 ? `${path3}: ${issue.message}` : issue.message;
       });
       return Err(
         createError(
@@ -1019,11 +1135,11 @@ function walk(node, visitor) {
 var TypeScriptParser = class {
   name = "typescript";
   extensions = [".ts", ".tsx", ".mts", ".cts"];
-  async parseFile(path2) {
-    const contentResult = await readFileContent(path2);
+  async parseFile(path3) {
+    const contentResult = await readFileContent(path3);
     if (!contentResult.ok) {
       return Err(
-        createParseError("NOT_FOUND", `File not found: ${path2}`, { path: path2 }, [
+        createParseError("NOT_FOUND", `File not found: ${path3}`, { path: path3 }, [
           "Check that the file exists",
           "Verify the path is correct"
         ])
@@ -1033,7 +1149,7 @@ var TypeScriptParser = class {
       const ast = parse(contentResult.value, {
         loc: true,
         range: true,
-        jsx: path2.endsWith(".tsx"),
+        jsx: path3.endsWith(".tsx"),
         errorOnUnknownASTType: false
       });
       return Ok({
@@ -1044,7 +1160,7 @@ var TypeScriptParser = class {
     } catch (e) {
       const error = e;
       return Err(
-        createParseError("SYNTAX_ERROR", `Failed to parse ${path2}: ${error.message}`, { path: path2 }, [
+        createParseError("SYNTAX_ERROR", `Failed to parse ${path3}: ${error.message}`, { path: path3 }, [
           "Check for syntax errors in the file",
           "Ensure valid TypeScript syntax"
         ])
@@ -1328,22 +1444,22 @@ function extractInlineRefs(content) {
   }
   return refs;
 }
-async function parseDocumentationFile(path2) {
-  const contentResult = await readFileContent(path2);
+async function parseDocumentationFile(path3) {
+  const contentResult = await readFileContent(path3);
   if (!contentResult.ok) {
     return Err(
       createEntropyError(
         "PARSE_ERROR",
-        `Failed to read documentation file: ${path2}`,
-        { file: path2 },
+        `Failed to read documentation file: ${path3}`,
+        { file: path3 },
         ["Check that the file exists"]
       )
     );
   }
   const content = contentResult.value;
-  const type = path2.endsWith(".md") ? "markdown" : "text";
+  const type = path3.endsWith(".md") ? "markdown" : "text";
   return Ok({
-    path: path2,
+    path: path3,
     type,
     content,
     codeBlocks: extractCodeBlocks(content),
@@ -1651,7 +1767,45 @@ async function checkStructureDrift(snapshot, _config) {
   }
   return drifts;
 }
-async function detectDocDrift(snapshot, config) {
+async function detectDocDrift(snapshot, config, graphDriftData) {
+  if (graphDriftData) {
+    const drifts2 = [];
+    for (const target of graphDriftData.missingTargets) {
+      drifts2.push({
+        type: "api-signature",
+        docFile: target,
+        line: 0,
+        reference: target,
+        context: "graph-missing-target",
+        issue: "NOT_FOUND",
+        details: `Graph node "${target}" has no matching code target`,
+        confidence: "high"
+      });
+    }
+    for (const edge of graphDriftData.staleEdges) {
+      drifts2.push({
+        type: "api-signature",
+        docFile: edge.docNodeId,
+        line: 0,
+        reference: edge.codeNodeId,
+        context: `graph-stale-edge:${edge.edgeType}`,
+        issue: "NOT_FOUND",
+        details: `Stale edge from doc "${edge.docNodeId}" to code "${edge.codeNodeId}" (${edge.edgeType})`,
+        confidence: "medium"
+      });
+    }
+    const severity2 = drifts2.length === 0 ? "none" : drifts2.length <= 3 ? "low" : drifts2.length <= 10 ? "medium" : "high";
+    return Ok({
+      drifts: drifts2,
+      stats: {
+        docsScanned: graphDriftData.staleEdges.length,
+        referencesChecked: graphDriftData.staleEdges.length + graphDriftData.missingTargets.length,
+        driftsFound: drifts2.length,
+        byType: { api: drifts2.length, example: 0, structure: 0 }
+      },
+      severity: severity2
+    });
+  }
   const fullConfig = { ...DEFAULT_DRIFT_CONFIG, ...config };
   const drifts = [];
   if (fullConfig.checkApiSignatures) {
@@ -1889,7 +2043,54 @@ function findDeadInternals(snapshot, _reachability) {
   }
   return deadInternals;
 }
-async function detectDeadCode(snapshot) {
+async function detectDeadCode(snapshot, graphDeadCodeData) {
+  if (graphDeadCodeData) {
+    const deadFiles2 = [];
+    const deadExports2 = [];
+    const fileTypes = /* @__PURE__ */ new Set(["file", "module"]);
+    const exportTypes = /* @__PURE__ */ new Set(["function", "class", "method", "interface", "variable"]);
+    for (const node of graphDeadCodeData.unreachableNodes) {
+      if (fileTypes.has(node.type)) {
+        deadFiles2.push({
+          path: node.path || node.id,
+          reason: "NO_IMPORTERS",
+          exportCount: 0,
+          lineCount: 0
+        });
+      } else if (exportTypes.has(node.type)) {
+        const exportType = node.type === "method" ? "function" : node.type;
+        deadExports2.push({
+          file: node.path || node.id,
+          name: node.name,
+          line: 0,
+          type: exportType,
+          isDefault: false,
+          reason: "NO_IMPORTERS"
+        });
+      }
+    }
+    const reachableCount = graphDeadCodeData.reachableNodeIds instanceof Set ? graphDeadCodeData.reachableNodeIds.size : graphDeadCodeData.reachableNodeIds.length;
+    const fileNodes = graphDeadCodeData.unreachableNodes.filter((n) => fileTypes.has(n.type));
+    const exportNodes = graphDeadCodeData.unreachableNodes.filter((n) => exportTypes.has(n.type));
+    const totalFiles = reachableCount + fileNodes.length;
+    const totalExports2 = exportNodes.length + (reachableCount > 0 ? reachableCount : 0);
+    const report2 = {
+      deadExports: deadExports2,
+      deadFiles: deadFiles2,
+      deadInternals: [],
+      unusedImports: [],
+      stats: {
+        filesAnalyzed: totalFiles,
+        entryPointsUsed: [],
+        totalExports: totalExports2,
+        deadExportCount: deadExports2.length,
+        totalFiles,
+        deadFileCount: deadFiles2.length,
+        estimatedDeadLines: 0
+      }
+    };
+    return Ok(report2);
+  }
   const reachability = buildReachabilityMap(snapshot);
   const usageMap = buildExportUsageMap(snapshot);
   const deadExports = findDeadExports(snapshot, usageMap, reachability);
@@ -2215,22 +2416,39 @@ var EntropyAnalyzer = class {
     };
   }
   /**
-   * Run full entropy analysis
+   * Run full entropy analysis.
+   * When graphOptions is provided, passes graph data to drift and dead code detectors
+   * for graph-enhanced analysis instead of snapshot-based analysis.
    */
-  async analyze() {
+  async analyze(graphOptions) {
     const startTime = Date.now();
-    const snapshotResult = await buildSnapshot(this.config);
-    if (!snapshotResult.ok) {
-      return Err(snapshotResult.error);
+    const needsSnapshot = !graphOptions || !graphOptions.graphDriftData || !graphOptions.graphDeadCodeData;
+    if (needsSnapshot) {
+      const snapshotResult = await buildSnapshot(this.config);
+      if (!snapshotResult.ok) {
+        return Err(snapshotResult.error);
+      }
+      this.snapshot = snapshotResult.value;
+    } else {
+      this.snapshot = {
+        files: [],
+        dependencyGraph: { nodes: [], edges: [] },
+        exportMap: { byFile: /* @__PURE__ */ new Map(), byName: /* @__PURE__ */ new Map() },
+        docs: [],
+        codeReferences: [],
+        entryPoints: [],
+        rootDir: this.config.rootDir,
+        config: this.config,
+        buildTime: 0
+      };
     }
-    this.snapshot = snapshotResult.value;
     let driftReport;
     let deadCodeReport;
     let patternReport;
     const analysisErrors = [];
     if (this.config.analyze.drift) {
       const driftConfig = typeof this.config.analyze.drift === "object" ? this.config.analyze.drift : {};
-      const result = await detectDocDrift(this.snapshot, driftConfig);
+      const result = await detectDocDrift(this.snapshot, driftConfig, graphOptions?.graphDriftData);
       if (result.ok) {
         driftReport = result.value;
       } else {
@@ -2238,7 +2456,7 @@ var EntropyAnalyzer = class {
       }
     }
     if (this.config.analyze.deadCode) {
-      const result = await detectDeadCode(this.snapshot);
+      const result = await detectDeadCode(this.snapshot, graphOptions?.graphDeadCodeData);
       if (result.ok) {
         deadCodeReport = result.value;
       } else {
@@ -2335,22 +2553,22 @@ var EntropyAnalyzer = class {
   /**
    * Run drift detection only (snapshot must be built first)
    */
-  async detectDrift(config) {
+  async detectDrift(config, graphDriftData) {
     const snapshotResult = await this.ensureSnapshot();
     if (!snapshotResult.ok) {
       return Err(snapshotResult.error);
     }
-    return detectDocDrift(snapshotResult.value, config || {});
+    return detectDocDrift(snapshotResult.value, config || {}, graphDriftData);
   }
   /**
    * Run dead code detection only (snapshot must be built first)
    */
-  async detectDeadCode() {
+  async detectDeadCode(graphDeadCodeData) {
     const snapshotResult = await this.ensureSnapshot();
     if (!snapshotResult.ok) {
       return Err(snapshotResult.error);
     }
-    return detectDeadCode(snapshotResult.value);
+    return detectDeadCode(snapshotResult.value, graphDeadCodeData);
   }
   /**
    * Run pattern detection only (snapshot must be built first)
@@ -2818,7 +3036,7 @@ function parseDiff(diff) {
     });
   }
 }
-async function analyzeDiff(changes, options) {
+async function analyzeDiff(changes, options, graphImpactData) {
   if (!options?.enabled) {
     return Ok([]);
   }
@@ -2869,26 +3087,75 @@ async function analyzeDiff(changes, options) {
     }
   }
   if (options.checkTestCoverage) {
-    const addedSourceFiles = changes.files.filter(
-      (f) => f.status === "added" && f.path.endsWith(".ts") && !f.path.includes(".test.")
-    );
-    const testFiles = changes.files.filter((f) => f.path.includes(".test."));
-    for (const sourceFile of addedSourceFiles) {
-      const expectedTestPath = sourceFile.path.replace(".ts", ".test.ts");
-      const hasTest = testFiles.some(
-        (t) => t.path.includes(expectedTestPath) || t.path.includes(sourceFile.path.replace(".ts", ""))
+    if (graphImpactData) {
+      for (const file of changes.files) {
+        if (file.status === "added" && file.path.endsWith(".ts") && !file.path.includes(".test.")) {
+          const hasGraphTest = graphImpactData.affectedTests.some(
+            (t) => t.coversFile === file.path
+          );
+          if (!hasGraphTest) {
+            items.push({
+              id: `test-coverage-${file.path}`,
+              category: "diff",
+              check: "Test coverage (graph)",
+              passed: false,
+              severity: "warning",
+              details: `New file ${file.path} has no test file linked in the graph`,
+              file: file.path
+            });
+          }
+        }
+      }
+    } else {
+      const addedSourceFiles = changes.files.filter(
+        (f) => f.status === "added" && f.path.endsWith(".ts") && !f.path.includes(".test.")
       );
-      if (!hasTest) {
-        items.push({
-          id: `diff-${++itemId}`,
-          category: "diff",
-          check: `Test coverage: ${sourceFile.path}`,
-          passed: false,
-          severity: "warning",
-          details: "New source file added without corresponding test file",
-          file: sourceFile.path,
-          suggestion: `Add tests in ${expectedTestPath}`
-        });
+      const testFiles = changes.files.filter((f) => f.path.includes(".test."));
+      for (const sourceFile of addedSourceFiles) {
+        const expectedTestPath = sourceFile.path.replace(".ts", ".test.ts");
+        const hasTest = testFiles.some(
+          (t) => t.path.includes(expectedTestPath) || t.path.includes(sourceFile.path.replace(".ts", ""))
+        );
+        if (!hasTest) {
+          items.push({
+            id: `diff-${++itemId}`,
+            category: "diff",
+            check: `Test coverage: ${sourceFile.path}`,
+            passed: false,
+            severity: "warning",
+            details: "New source file added without corresponding test file",
+            file: sourceFile.path,
+            suggestion: `Add tests in ${expectedTestPath}`
+          });
+        }
+      }
+    }
+  }
+  if (graphImpactData && graphImpactData.impactScope > 20) {
+    items.push({
+      id: "impact-scope",
+      category: "diff",
+      check: "Impact scope",
+      passed: false,
+      severity: "warning",
+      details: `Changes affect ${graphImpactData.impactScope} downstream dependents \u2014 consider a thorough review`
+    });
+  }
+  if (graphImpactData) {
+    for (const file of changes.files) {
+      if (file.status === "modified" && file.path.endsWith(".ts") && !file.path.includes(".test.")) {
+        const hasDoc = graphImpactData.affectedDocs.some((d) => d.documentsFile === file.path);
+        if (!hasDoc) {
+          items.push({
+            id: `doc-coverage-${file.path}`,
+            category: "diff",
+            check: "Documentation coverage (graph)",
+            passed: true,
+            severity: "info",
+            details: `Modified file ${file.path} has no documentation linked in the graph`,
+            file: file.path
+          });
+        }
       }
     }
   }
@@ -2899,13 +3166,16 @@ async function analyzeDiff(changes, options) {
 var ChecklistBuilder = class {
   rootDir;
   harnessOptions;
+  graphHarnessData;
   customRules = [];
   diffOptions;
+  graphImpactData;
   constructor(rootDir) {
     this.rootDir = rootDir;
   }
-  withHarnessChecks(options) {
+  withHarnessChecks(options, graphData) {
     this.harnessOptions = options ?? { context: true, constraints: true, entropy: true };
+    this.graphHarnessData = graphData;
     return this;
   }
   addRule(rule) {
@@ -2916,46 +3186,79 @@ var ChecklistBuilder = class {
     this.customRules.push(...rules);
     return this;
   }
-  withDiffAnalysis(options) {
+  withDiffAnalysis(options, graphImpactData) {
     this.diffOptions = options;
+    this.graphImpactData = graphImpactData;
     return this;
   }
   async run(changes) {
     const startTime = Date.now();
     const items = [];
     if (this.harnessOptions) {
-      if (this.harnessOptions.context) {
-        items.push({
-          id: "harness-context",
-          category: "harness",
-          check: "Context Engineering (AGENTS.md, doc coverage)",
-          passed: true,
-          severity: "info",
-          details: "Harness context validation not yet integrated. See Module 2 (context/).",
-          suggestion: "Integrate with validateAgentsMap(), checkDocCoverage() from context module"
-        });
+      if (this.harnessOptions.context !== false) {
+        if (this.graphHarnessData) {
+          items.push({
+            id: "harness-context",
+            category: "harness",
+            check: "Context validation",
+            passed: this.graphHarnessData.graphExists && this.graphHarnessData.nodeCount > 0,
+            severity: "info",
+            details: this.graphHarnessData.graphExists ? `Graph loaded: ${this.graphHarnessData.nodeCount} nodes, ${this.graphHarnessData.edgeCount} edges` : "No graph available \u2014 run harness scan to build the knowledge graph"
+          });
+        } else {
+          items.push({
+            id: "harness-context",
+            category: "harness",
+            check: "Context validation",
+            passed: true,
+            severity: "info",
+            details: "Harness context validation not yet integrated (run with graph for real checks)"
+          });
+        }
       }
-      if (this.harnessOptions.constraints) {
-        items.push({
-          id: "harness-constraints",
-          category: "harness",
-          check: "Architectural Constraints (dependencies, boundaries)",
-          passed: true,
-          severity: "info",
-          details: "Harness constraints validation not yet integrated. See Module 3 (constraints/).",
-          suggestion: "Integrate with validateDependencies(), detectCircularDeps() from constraints module"
-        });
+      if (this.harnessOptions.constraints !== false) {
+        if (this.graphHarnessData) {
+          const violations = this.graphHarnessData.constraintViolations;
+          items.push({
+            id: "harness-constraints",
+            category: "harness",
+            check: "Constraint validation",
+            passed: violations === 0,
+            severity: violations > 0 ? "error" : "info",
+            details: violations === 0 ? "No constraint violations detected" : `${violations} constraint violation(s) detected`
+          });
+        } else {
+          items.push({
+            id: "harness-constraints",
+            category: "harness",
+            check: "Constraint validation",
+            passed: true,
+            severity: "info",
+            details: "Harness constraint validation not yet integrated (run with graph for real checks)"
+          });
+        }
       }
-      if (this.harnessOptions.entropy) {
-        items.push({
-          id: "harness-entropy",
-          category: "harness",
-          check: "Entropy Management (drift, dead code)",
-          passed: true,
-          severity: "info",
-          details: "Harness entropy validation not yet integrated. See Module 4 (entropy/).",
-          suggestion: "Integrate with EntropyAnalyzer from entropy module"
-        });
+      if (this.harnessOptions.entropy !== false) {
+        if (this.graphHarnessData) {
+          const issues = this.graphHarnessData.unreachableNodes + this.graphHarnessData.undocumentedFiles;
+          items.push({
+            id: "harness-entropy",
+            category: "harness",
+            check: "Entropy detection",
+            passed: issues === 0,
+            severity: issues > 0 ? "warning" : "info",
+            details: issues === 0 ? "No entropy issues detected" : `${this.graphHarnessData.unreachableNodes} unreachable node(s), ${this.graphHarnessData.undocumentedFiles} undocumented file(s)`
+          });
+        } else {
+          items.push({
+            id: "harness-entropy",
+            category: "harness",
+            check: "Entropy detection",
+            passed: true,
+            severity: "info",
+            details: "Harness entropy detection not yet integrated (run with graph for real checks)"
+          });
+        }
       }
     }
     for (const rule of this.customRules) {
@@ -2991,7 +3294,7 @@ var ChecklistBuilder = class {
       }
     }
     if (this.diffOptions) {
-      const diffResult = await analyzeDiff(changes, this.diffOptions);
+      const diffResult = await analyzeDiff(changes, this.diffOptions, this.graphImpactData);
       if (diffResult.ok) {
         items.push(...diffResult.value);
       }
@@ -3018,16 +3321,16 @@ var ChecklistBuilder = class {
 };
 
 // src/feedback/review/self-review.ts
-async function createSelfReview(changes, config) {
+async function createSelfReview(changes, config, graphData) {
   const builder = new ChecklistBuilder(config.rootDir);
   if (config.harness) {
-    builder.withHarnessChecks(config.harness);
+    builder.withHarnessChecks(config.harness, graphData?.harness);
   }
   if (config.customRules) {
     builder.addRules(config.customRules);
   }
   if (config.diffAnalysis) {
-    builder.withDiffAnalysis(config.diffAnalysis);
+    builder.withDiffAnalysis(config.diffAnalysis, graphData?.impact);
   }
   return builder.run(changes);
 }
@@ -3854,6 +4157,188 @@ async function runMultiTurnPipeline(initialContext, turnExecutor, options) {
   };
 }
 
+// src/ci/check-orchestrator.ts
+import * as path2 from "path";
+var ALL_CHECKS = ["validate", "deps", "docs", "entropy", "phase-gate"];
+async function runSingleCheck(name, projectRoot, config) {
+  const start = Date.now();
+  const issues = [];
+  try {
+    switch (name) {
+      case "validate": {
+        const agentsPath = path2.join(projectRoot, config.agentsMapPath ?? "AGENTS.md");
+        const result = await validateAgentsMap(agentsPath);
+        if (!result.ok) {
+          issues.push({ severity: "error", message: result.error.message });
+        } else if (!result.value.valid) {
+          if (result.value.errors) {
+            for (const err of result.value.errors) {
+              issues.push({ severity: "error", message: err.message });
+            }
+          }
+          for (const section of result.value.missingSections) {
+            issues.push({ severity: "warning", message: `Missing section: ${section}` });
+          }
+          for (const link of result.value.brokenLinks) {
+            issues.push({
+              severity: "warning",
+              message: `Broken link: ${link.text} \u2192 ${link.path}`,
+              file: link.path
+            });
+          }
+        }
+        break;
+      }
+      case "deps": {
+        const rawLayers = config.layers;
+        if (rawLayers && rawLayers.length > 0) {
+          const parser = new TypeScriptParser();
+          const layers = rawLayers.map(
+            (l) => defineLayer(
+              l.name,
+              Array.isArray(l.patterns) ? l.patterns : [l.pattern],
+              l.allowedDependencies
+            )
+          );
+          const result = await validateDependencies({
+            layers,
+            rootDir: projectRoot,
+            parser
+          });
+          if (!result.ok) {
+            issues.push({ severity: "error", message: result.error.message });
+          } else if (result.value.violations.length > 0) {
+            for (const v of result.value.violations) {
+              issues.push({
+                severity: "error",
+                message: `${v.reason}: ${v.file} imports ${v.imports} (${v.fromLayer} \u2192 ${v.toLayer})`,
+                file: v.file,
+                line: v.line
+              });
+            }
+          }
+        }
+        break;
+      }
+      case "docs": {
+        const docsDir = path2.join(projectRoot, config.docsDir ?? "docs");
+        const result = await checkDocCoverage("project", { docsDir });
+        if (!result.ok) {
+          issues.push({ severity: "warning", message: result.error.message });
+        } else if (result.value.gaps.length > 0) {
+          for (const gap of result.value.gaps) {
+            issues.push({
+              severity: "warning",
+              message: `Undocumented: ${gap.file} (suggested: ${gap.suggestedSection})`,
+              file: gap.file
+            });
+          }
+        }
+        break;
+      }
+      case "entropy": {
+        const analyzer = new EntropyAnalyzer({
+          rootDir: projectRoot,
+          analyze: { drift: true, deadCode: true, patterns: false }
+        });
+        const result = await analyzer.analyze();
+        if (!result.ok) {
+          issues.push({ severity: "warning", message: result.error.message });
+        } else {
+          const report = result.value;
+          if (report.drift) {
+            for (const drift of report.drift.drifts) {
+              issues.push({
+                severity: "warning",
+                message: `Doc drift (${drift.type}): ${drift.details}`,
+                file: drift.docFile,
+                line: drift.line
+              });
+            }
+          }
+          if (report.deadCode) {
+            for (const dead of report.deadCode.deadExports) {
+              issues.push({
+                severity: "warning",
+                message: `Dead export: ${dead.name}`,
+                file: dead.file,
+                line: dead.line
+              });
+            }
+          }
+        }
+        break;
+      }
+      case "phase-gate": {
+        const phaseGates = config.phaseGates;
+        if (!phaseGates?.enabled) {
+          break;
+        }
+        issues.push({
+          severity: "warning",
+          message: "Phase gate is enabled but requires CLI context. Run `harness check-phase-gate` separately for full validation."
+        });
+        break;
+      }
+    }
+  } catch (error) {
+    issues.push({
+      severity: "error",
+      message: `Check '${name}' threw: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+  const hasErrors = issues.some((i) => i.severity === "error");
+  const hasWarnings = issues.some((i) => i.severity === "warning");
+  const status = hasErrors ? "fail" : hasWarnings ? "warn" : "pass";
+  return {
+    name,
+    status,
+    issues,
+    durationMs: Date.now() - start
+  };
+}
+function buildSummary(checks) {
+  return {
+    total: checks.length,
+    passed: checks.filter((c) => c.status === "pass").length,
+    failed: checks.filter((c) => c.status === "fail").length,
+    warnings: checks.filter((c) => c.status === "warn").length,
+    skipped: checks.filter((c) => c.status === "skip").length
+  };
+}
+function determineExitCode(summary, failOn = "error") {
+  if (summary.failed > 0) return 1;
+  if (failOn === "warning" && summary.warnings > 0) return 1;
+  return 0;
+}
+async function runCIChecks(input) {
+  const { projectRoot, config, skip = [], failOn = "error" } = input;
+  try {
+    const checks = [];
+    for (const name of ALL_CHECKS) {
+      if (skip.includes(name)) {
+        checks.push({ name, status: "skip", issues: [], durationMs: 0 });
+      } else {
+        const result = await runSingleCheck(name, projectRoot, config);
+        checks.push(result);
+      }
+    }
+    const summary = buildSummary(checks);
+    const exitCode = determineExitCode(summary, failOn);
+    const report = {
+      version: 1,
+      project: config.name ?? "unknown",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      checks,
+      summary,
+      exitCode
+    };
+    return Ok(report);
+  } catch (error) {
+    return Err(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
 // src/index.ts
 var VERSION = "0.6.0";
 export {
@@ -3917,6 +4402,7 @@ export {
   requestPeerReview,
   resetFeedbackConfig,
   resolveFileToLayer,
+  runCIChecks,
   runMechanicalGate,
   runMultiTurnPipeline,
   runPipeline,