@harness-engineering/cli 1.26.1 → 1.27.0

package/dist/{chunk-2FPUPRCY.js → chunk-GAIOIINV.js}

@@ -19,22 +19,26 @@ import * as fs3 from "fs/promises";
 import * as path4 from "path";
 import * as fs4 from "fs/promises";
 import * as path5 from "path";
-import * as fs9 from "fs/promises";
-import * as path10 from "path";
 import * as fs5 from "fs/promises";
 import * as path6 from "path";
+import * as fs11 from "fs/promises";
+import * as path12 from "path";
 import * as fs6 from "fs/promises";
 import * as path7 from "path";
 import * as fs7 from "fs/promises";
 import * as path8 from "path";
 import * as fs8 from "fs/promises";
 import * as path9 from "path";
+import * as fs9 from "fs/promises";
+import * as path10 from "path";
 import * as fs10 from "fs/promises";
 import * as path11 from "path";
+import * as fs12 from "fs/promises";
+import * as path13 from "path";
 import { minimatch } from "minimatch";
 import { relative as relative5 } from "path";
-import * as fs11 from "fs/promises";
-import * as path12 from "path";
+import * as fs13 from "fs/promises";
+import * as path14 from "path";
 function streamGraphJson(filePath, nodes, edges) {
   return new Promise((resolve, reject) => {
     const stream = createWriteStream(filePath, { encoding: "utf-8" });
@@ -50,7 +54,7 @@ function streamGraphJson(filePath, nodes, edges) {
       stream.write(JSON.stringify(edges[i]));
     }
     stream.write("]}");
-    stream.end(resolve);
+    stream.end(() => resolve());
   });
 }
 async function saveGraph(dirPath, nodes, edges) {
@@ -73,15 +77,19 @@ async function loadGraph(dirPath) {
     await access(metaPath);
     await access(graphPath);
   } catch {
-    return null;
+    return { status: "not_found" };
   }
   const metaContent = await readFile(metaPath, "utf-8");
   const metadata = JSON.parse(metaContent);
   if (metadata.schemaVersion !== CURRENT_SCHEMA_VERSION) {
-    return null;
+    return {
+      status: "schema_mismatch",
+      found: metadata.schemaVersion,
+      expected: CURRENT_SCHEMA_VERSION
+    };
   }
   const graphContent = await readFile(graphPath, "utf-8");
-  return JSON.parse(graphContent);
+  return { status: "loaded", graph: JSON.parse(graphContent) };
 }
 function safeMerge(target, source) {
   for (const key of Object.keys(source)) {
@@ -646,11 +654,11 @@ function applyReactionBoost(candidate, nodeType, metadata) {
   }
 }
 function detectLanguage(filePath) {
-  const name = path9.basename(filePath);
+  const name = path10.basename(filePath);
   for (const skip of SKIP_EXTENSIONS2) {
     if (name.endsWith(skip)) return void 0;
   }
-  const ext = path9.extname(filePath);
+  const ext = path10.extname(filePath);
   return EXT_TO_LANGUAGE[ext];
 }
 function createExtractionRunner() {
@@ -865,7 +873,7 @@ function sanitizeExternalText(text, maxLength = 2e3) {
 }
 function linkToCode(store, content, sourceNodeId, edgeType, options) {
   let edgesCreated = 0;
-  for (const type of CODE_NODE_TYPES4) {
+  for (const type of CODE_NODE_TYPES5) {
     const nodes = store.findNodes({ type });
     for (const node of nodes) {
       if (node.name.length < 3) continue;
@@ -1353,7 +1361,7 @@ function isDTCGToken(obj) {
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs11.readFile(filePath, "utf-8");
+    return await fs13.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -1435,7 +1443,7 @@ function parseAntiPatterns(content) {
   }
   return patterns;
 }
-var NODE_TYPES, EDGE_TYPES, OBSERVABILITY_TYPES, CURRENT_SCHEMA_VERSION, NODE_STABILITY, GraphNodeSchema, GraphEdgeSchema, POISONED_KEYS, GraphStore, VectorStore, DEFAULT_TTL_MS, PackedSummaryCache, ContextQL, TEST_TYPES, DOC_TYPES, CODE_TYPES, SKIP_METHOD_NAMES, FUNCTION_PATTERNS, CLASS_PATTERNS, INTERFACE_PATTERNS, METHOD_PATTERNS, GO_METHOD_PATTERN, VARIABLE_PATTERNS, SUPPORTED_EXTENSIONS, SKIP_EXTENSIONS, CodeIngestor, execFileAsync, GitIngestor, TopologicalLinker, CODE_NODE_TYPES, KnowledgeIngestor, BUSINESS_KNOWLEDGE_TYPES, GOVERNS_SOURCE_TYPES, CODE_NODE_TYPES2, MEASURABLE_TYPES, BusinessKnowledgeIngestor, REQUIREMENT_SECTIONS, SECTION_HEADING_RE, NUMBERED_ITEM_RE, CODE_NODE_TYPES3, RequirementIngestor, MermaidParser, D2Parser, PlantUmlParser, DIAGRAM_EXTENSIONS, SKIP_DIRS, DiagramParser, HEURISTIC_PATTERNS, SCANNABLE_TYPES, KnowledgeLinker, StructuralDriftDetector, KnowledgeStagingAggregator, SKIP_DIRS2, EXT_TO_LANGUAGE, SKIP_EXTENSIONS2, EXTRACTOR_EDGE_TYPE, ExtractionRunner, PATTERNS, TestDescriptionExtractor, EnumConstantExtractor, ValidationRuleExtractor, ApiPathExtractor, ALL_EXTRACTORS, ImageAnalysisExtractor, KNOWLEDGE_NODE_TYPES, SIMILARITY_THRESHOLD, SEVERITY_MAP, ContradictionDetector, KNOWLEDGE_TYPES, CODE_TYPES2, KNOWLEDGE_EDGE_TYPES, CoverageScorer, BUSINESS_NODE_TYPES, SNAPSHOT_NODE_TYPES, KnowledgePipelineRunner, CODE_NODE_TYPES4, RETRYABLE_STATUSES, SANITIZE_RULES, SyncManager, SUMMARIZE_PROMPT, JiraConnector, SlackConnector, ConfluenceConnector, CIConnector, CONSTRAINT_KEYWORDS, FigmaConnector, MIN_CONTENT_LENGTH, CONCEPT_ITEM_TYPES, MiroConnector, STOP_WORDS, FusionLayer, CODE_NODE_TYPES5, GraphEntropyAdapter, GraphComplexityAdapter, GraphCouplingAdapter, DEFAULT_THRESHOLD, DEFAULT_METRICS, RECOGNIZED_METRICS, GraphAnomalyAdapter, INTENTS, SIGNAL_WEIGHTS, INTENT_SIGNALS, IntentClassifier, INTENT_KEYWORDS, STOP_WORDS2, PASCAL_OR_CAMEL_RE, FILE_PATH_RE, QUOTED_RE, EntityExtractor, EntityResolver, ResponseFormatter, CompositeProbabilityStrategy, DEFAULT_PROBABILITY_FLOOR, DEFAULT_MAX_DEPTH, CascadeSimulator, ENTITY_REQUIRED_INTENTS, classifier, extractor, formatter, PHASE_NODE_TYPES, CODE_NODE_TYPES6, Assembler, GraphConstraintAdapter, DesignIngestor, DesignConstraintAdapter, GraphFeedbackAdapter, DEFAULT_EDGE_TYPES, TaskIndependenceAnalyzer, ConflictPredictor, VERSION;
+var NODE_TYPES, EDGE_TYPES, OBSERVABILITY_TYPES, CURRENT_SCHEMA_VERSION, NODE_STABILITY, GraphNodeSchema, GraphEdgeSchema, POISONED_KEYS, GraphStore, VectorStore, DEFAULT_TTL_MS, PackedSummaryCache, ContextQL, TEST_TYPES, DOC_TYPES, CODE_TYPES, SKIP_METHOD_NAMES, FUNCTION_PATTERNS, CLASS_PATTERNS, INTERFACE_PATTERNS, METHOD_PATTERNS, GO_METHOD_PATTERN, VARIABLE_PATTERNS, SUPPORTED_EXTENSIONS, SKIP_EXTENSIONS, CodeIngestor, execFileAsync, GitIngestor, TopologicalLinker, CODE_NODE_TYPES, KnowledgeIngestor, BUSINESS_KNOWLEDGE_TYPES, GOVERNS_SOURCE_TYPES, CODE_NODE_TYPES2, MEASURABLE_TYPES, BusinessKnowledgeIngestor, CODE_NODE_TYPES3, DecisionIngestor, REQUIREMENT_SECTIONS, SECTION_HEADING_RE, NUMBERED_ITEM_RE, CODE_NODE_TYPES4, RequirementIngestor, MermaidParser, D2Parser, PlantUmlParser, DIAGRAM_EXTENSIONS, SKIP_DIRS, DiagramParser, HEURISTIC_PATTERNS, SCANNABLE_TYPES, KnowledgeLinker, StructuralDriftDetector, BUSINESS_NODE_TYPES, KnowledgeStagingAggregator, SKIP_DIRS2, EXT_TO_LANGUAGE, SKIP_EXTENSIONS2, EXTRACTOR_EDGE_TYPE, ExtractionRunner, PATTERNS, TestDescriptionExtractor, EnumConstantExtractor, ValidationRuleExtractor, ApiPathExtractor, ALL_EXTRACTORS, ImageAnalysisExtractor, KNOWLEDGE_NODE_TYPES, SIMILARITY_THRESHOLD, SEVERITY_MAP, ContradictionDetector, KNOWLEDGE_TYPES, CODE_TYPES2, KNOWLEDGE_EDGE_TYPES, CoverageScorer, VALID_BUSINESS_TYPES, DEFAULT_MAX_DOCS, MAX_COLLISION_SUFFIX, KnowledgeDocMaterializer, BUSINESS_NODE_TYPES2, SNAPSHOT_NODE_TYPES, KnowledgePipelineRunner, CODE_NODE_TYPES5, RETRYABLE_STATUSES, SANITIZE_RULES, SyncManager, SUMMARIZE_PROMPT, JiraConnector, SlackConnector, ConfluenceConnector, CIConnector, CONSTRAINT_KEYWORDS, FigmaConnector, MIN_CONTENT_LENGTH, CONCEPT_ITEM_TYPES, MiroConnector, STOP_WORDS, FusionLayer, CODE_NODE_TYPES6, GraphEntropyAdapter, GraphComplexityAdapter, GraphCouplingAdapter, DEFAULT_THRESHOLD, DEFAULT_METRICS, RECOGNIZED_METRICS, GraphAnomalyAdapter, INTENTS, SIGNAL_WEIGHTS, INTENT_SIGNALS, IntentClassifier, INTENT_KEYWORDS, STOP_WORDS2, PASCAL_OR_CAMEL_RE, FILE_PATH_RE, QUOTED_RE, EntityExtractor, EntityResolver, ResponseFormatter, CompositeProbabilityStrategy, DEFAULT_PROBABILITY_FLOOR, DEFAULT_MAX_DEPTH, CascadeSimulator, ENTITY_REQUIRED_INTENTS, classifier, extractor, formatter, PHASE_NODE_TYPES, CODE_NODE_TYPES7, Assembler, GraphConstraintAdapter, DesignIngestor, DesignConstraintAdapter, GraphFeedbackAdapter, DEFAULT_EDGE_TYPES, TaskIndependenceAnalyzer, ConflictPredictor, VERSION;
 var init_dist = __esm({
   "../graph/dist/index.mjs"() {
     NODE_TYPES = [
@@ -1462,7 +1470,7 @@ var init_dist = __esm({
       "build",
       "test_result",
       "execution_outcome",
-      // Observability (future)
+      // Observability — reserved for future tracing/metrics integration
       "span",
       "metric",
       "log",
@@ -1509,7 +1517,7 @@ var init_dist = __esm({
       "triggered_by",
       "failed_in",
       "outcome_of",
-      // Execution relationships (future)
+      // Execution relationships — reserved for future observability integration
       "executed_by",
       "measured_by",
       // Design relationships
@@ -1700,8 +1708,15 @@ var init_dist = __esm({
         await saveGraph(dirPath, allNodes, allEdges);
       }
       async load(dirPath) {
-        const data = await loadGraph(dirPath);
-        if (!data) return false;
+        const result = await loadGraph(dirPath);
+        if (result.status === "not_found") return false;
+        if (result.status === "schema_mismatch") {
+          console.warn(
+            `[graph] Schema version mismatch: graph was saved with v${result.found} but current is v${result.expected}. Graph will be rebuilt from scratch. Run \`harness graph scan\` to repopulate.`
+          );
+          return false;
+        }
+        const data = result.graph;
         this.clear();
         for (const node of data.nodes) {
           this.nodeMap.set(node.id, { ...node });
@@ -2014,9 +2029,10 @@ var init_dist = __esm({
         let edgesAdded = 0;
         const files = await this.findSourceFiles(rootDir);
         const nameToFiles = /* @__PURE__ */ new Map();
+        const contentCache = /* @__PURE__ */ new Map();
         for (const filePath of files) {
           try {
-            const result = await this.processFile(filePath, rootDir, nameToFiles);
+            const result = await this.processFile(filePath, rootDir, nameToFiles, contentCache);
             nodesAdded += result.nodesAdded;
             edgesAdded += result.edgesAdded;
           } catch (err) {
@@ -2026,7 +2042,8 @@ var init_dist = __esm({
         for (const filePath of files) {
           try {
             const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
-            const content = await fs.readFile(filePath, "utf-8");
+            const content = contentCache.get(filePath);
+            if (content === void 0) continue;
             const callsEdges = this.extractCallsEdgesForFile(relativePath, content, nameToFiles);
             for (const edge of callsEdges) {
               this.store.addEdge(edge);
@@ -2037,7 +2054,8 @@ var init_dist = __esm({
         }
         for (const filePath of files) {
           try {
-            const content = await fs.readFile(filePath, "utf-8");
+            const content = contentCache.get(filePath);
+            if (content === void 0) continue;
             edgesAdded += this.extractReqAnnotationsForFile(filePath, content, rootDir);
           } catch {
           }
@@ -2051,11 +2069,12 @@ var init_dist = __esm({
           durationMs: Date.now() - start
         };
       }
-      async processFile(filePath, rootDir, nameToFiles) {
+      async processFile(filePath, rootDir, nameToFiles, contentCache) {
         let nodesAdded = 0;
         let edgesAdded = 0;
         const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
         const content = await fs.readFile(filePath, "utf-8");
+        contentCache.set(filePath, content);
         const stat2 = await fs.stat(filePath);
         const fileId = `file:${relativePath}`;
         const fileNode = {
@@ -3093,6 +3112,112 @@ var init_dist = __esm({
         return results;
       }
     };
+    CODE_NODE_TYPES3 = [
+      "file",
+      "function",
+      "class",
+      "method",
+      "interface",
+      "variable"
+    ];
+    DecisionIngestor = class {
+      constructor(store) {
+        this.store = store;
+      }
+      store;
+      async ingest(decisionsDir) {
+        const start = Date.now();
+        const errors = [];
+        let files;
+        try {
+          files = await this.findDecisionFiles(decisionsDir);
+        } catch {
+          return emptyResult(Date.now() - start);
+        }
+        let nodesAdded = 0;
+        let edgesAdded = 0;
+        for (const filePath of files) {
+          try {
+            const raw = await fs4.readFile(filePath, "utf-8");
+            const parsed = this.parseFrontmatter(raw);
+            if (!parsed) continue;
+            const { frontmatter, body } = parsed;
+            if (!frontmatter.number || !frontmatter.title) continue;
+            const filename = path5.basename(filePath, ".md");
+            const nodeId = `decision:${filename}`;
+            const node = {
+              id: nodeId,
+              type: "decision",
+              name: frontmatter.title,
+              path: filePath,
+              content: body.trim(),
+              metadata: {
+                number: frontmatter.number,
+                ...frontmatter.date && { date: frontmatter.date },
+                ...frontmatter.status && { status: frontmatter.status },
+                ...frontmatter.tier && { tier: frontmatter.tier },
+                ...frontmatter.source && { source: frontmatter.source },
+                ...frontmatter.supersedes && { supersedes: frontmatter.supersedes }
+              }
+            };
+            this.store.addNode(node);
+            nodesAdded++;
+            edgesAdded += this.linkToCode(body, nodeId);
+          } catch (err) {
+            errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+        return {
+          nodesAdded,
+          nodesUpdated: 0,
+          edgesAdded,
+          edgesUpdated: 0,
+          errors,
+          durationMs: Date.now() - start
+        };
+      }
+      parseFrontmatter(raw) {
+        const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+        if (!match) return null;
+        const yamlBlock = match[1];
+        const body = match[2];
+        const frontmatter = {};
+        for (const line of yamlBlock.split("\n")) {
+          const kvMatch = line.match(/^(\w+):\s*(.+)$/);
+          if (!kvMatch) continue;
+          frontmatter[kvMatch[1]] = kvMatch[2].trim();
+        }
+        if (!frontmatter.number || !frontmatter.title) return null;
+        return {
+          frontmatter,
+          body
+        };
+      }
+      linkToCode(content, sourceNodeId) {
+        let count = 0;
+        for (const nodeType of CODE_NODE_TYPES3) {
+          const codeNodes = this.store.findNodes({ type: nodeType });
+          for (const node of codeNodes) {
+            if (node.name.length < 3) continue;
+            const escaped = node.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const namePattern = new RegExp(`\\b${escaped}\\b`, "i");
+            if (namePattern.test(content)) {
+              this.store.addEdge({
+                from: sourceNodeId,
+                to: node.id,
+                type: "decided"
+              });
+              count++;
+            }
+          }
+        }
+        return count;
+      }
+      async findDecisionFiles(dir) {
+        const entries = await fs4.readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile() && e.name.endsWith(".md") && e.name !== "README.md").map((e) => path5.join(dir, e.name));
+      }
+    };
     REQUIREMENT_SECTIONS = [
       "Observable Truths",
       "Success Criteria",
@@ -3100,7 +3225,7 @@ var init_dist = __esm({
     ];
     SECTION_HEADING_RE = /^#{2,3}\s+(.+)$/;
     NUMBERED_ITEM_RE = /^\s*(\d+)\.\s+(.+)$/;
-    CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
     RequirementIngestor = class {
       constructor(store) {
         this.store = store;
@@ -3118,8 +3243,8 @@ var init_dist = __esm({
         let edgesAdded = 0;
         let featureDirs;
         try {
-          const entries = await fs4.readdir(specsDir, { withFileTypes: true });
-          featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path5.join(specsDir, e.name));
+          const entries = await fs5.readdir(specsDir, { withFileTypes: true });
+          featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path6.join(specsDir, e.name));
         } catch {
           return emptyResult(Date.now() - start);
         }
@@ -3138,11 +3263,11 @@ var init_dist = __esm({
         };
       }
       async ingestFeatureDir(featureDir, errors) {
-        const featureName = path5.basename(featureDir);
-        const specPath = path5.join(featureDir, "proposal.md").replaceAll("\\", "/");
+        const featureName = path6.basename(featureDir);
+        const specPath = path6.join(featureDir, "proposal.md").replaceAll("\\", "/");
         let content;
         try {
-          content = await fs4.readFile(specPath, "utf-8");
+          content = await fs5.readFile(specPath, "utf-8");
         } catch {
           return { nodesAdded: 0, edgesAdded: 0 };
         }
@@ -3159,7 +3284,7 @@ var init_dist = __esm({
         this.store.addNode({
           id: specNodeId,
           type: "document",
-          name: path5.basename(specPath),
+          name: path6.basename(specPath),
           path: specPath,
           metadata: { featureName }
         });
@@ -3274,9 +3399,9 @@ var init_dist = __esm({
         for (const node of fileNodes) {
           if (!node.path) continue;
           const normalizedPath = node.path.replace(/\\/g, "/");
-          const isCodeMatch = normalizedPath.includes("packages/") && path5.basename(normalizedPath).includes(featureName);
+          const isCodeMatch = normalizedPath.includes("packages/") && path6.basename(normalizedPath).includes(featureName);
           const isTestMatch = normalizedPath.includes("/tests/") && // platform-safe
-          path5.basename(normalizedPath).includes(featureName);
+          path6.basename(normalizedPath).includes(featureName);
           if (isCodeMatch && !isTestMatch) {
             this.store.addEdge({
               from: reqId,
@@ -3305,7 +3430,7 @@ var init_dist = __esm({
        */
       linkByKeywordOverlap(reqId, reqText) {
         let count = 0;
-        for (const nodeType of CODE_NODE_TYPES3) {
+        for (const nodeType of CODE_NODE_TYPES4) {
           const codeNodes = this.store.findNodes({ type: nodeType });
           for (const node of codeNodes) {
             if (node.name.length < 3) continue;
@@ -3402,7 +3527,7 @@ var init_dist = __esm({
         new PlantUmlParser()
       ];
       parse(content, filePath) {
-        const ext = path6.extname(filePath).toLowerCase();
+        const ext = path7.extname(filePath).toLowerCase();
         for (const parser of this.parsers) {
           if (parser.canParse(content, ext)) {
             return parser.parse(content, filePath);
@@ -3422,8 +3547,8 @@ var init_dist = __esm({
         const diagramFiles = await this.findDiagramFiles(projectDir);
         for (const filePath of diagramFiles) {
           try {
-            const content = await fs5.readFile(filePath, "utf-8");
-            const relPath = path6.relative(projectDir, filePath).replaceAll("\\", "/");
+            const content = await fs6.readFile(filePath, "utf-8");
+            const relPath = path7.relative(projectDir, filePath).replaceAll("\\", "/");
             const result = this.parse(content, filePath);
             if (result.entities.length === 0) continue;
             const pathHash = hash(relPath);
@@ -3489,19 +3614,19 @@ var init_dist = __esm({
         const walk = async (currentDir) => {
           let entries;
           try {
-            entries = await fs5.readdir(currentDir, { withFileTypes: true });
+            entries = await fs6.readdir(currentDir, { withFileTypes: true });
           } catch {
             return;
           }
           for (const entry of entries) {
             if (entry.isDirectory()) {
               if (!SKIP_DIRS.has(entry.name)) {
-                await walk(path6.join(currentDir, entry.name));
+                await walk(path7.join(currentDir, entry.name));
               }
             } else if (entry.isFile()) {
-              const ext = path6.extname(entry.name).toLowerCase();
+              const ext = path7.extname(entry.name).toLowerCase();
               if (DIAGRAM_EXTENSIONS.has(ext)) {
-                files.push(path6.join(currentDir, entry.name));
+                files.push(path7.join(currentDir, entry.name));
               }
             }
           }
@@ -3648,8 +3773,10 @@ var init_dist = __esm({
         if (!duplicate) return false;
         const existingSources = duplicate.metadata.sources ?? [];
         if (!existingSources.includes(candidate.sourceNodeId)) {
-          existingSources.push(candidate.sourceNodeId);
-          duplicate.metadata.sources = existingSources;
+          this.store.addNode({
+            ...duplicate,
+            metadata: { ...duplicate.metadata, sources: [...existingSources, candidate.sourceNodeId] }
+          });
         }
         return true;
       }
@@ -3683,8 +3810,8 @@ var init_dist = __esm({
        */
       async writeJsonl(candidates) {
         if (!this.outputDir) return;
-        await fs6.mkdir(this.outputDir, { recursive: true });
-        const filePath = path7.join(this.outputDir, "linker.jsonl");
+        await fs7.mkdir(this.outputDir, { recursive: true });
+        const filePath = path8.join(this.outputDir, "linker.jsonl");
         const lines = candidates.map(
           (c) => JSON.stringify({
             id: c.id,
@@ -3697,16 +3824,16 @@ var init_dist = __esm({
             nodeType: c.nodeType
           })
         );
-        await fs6.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
+        await fs7.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
       }
       /**
        * Write medium-confidence candidates to staged JSONL for human review.
        */
       async writeStagedJsonl(candidates) {
         if (!this.outputDir || candidates.length === 0) return;
-        const stagedDir = path7.join(this.outputDir, "staged");
-        await fs6.mkdir(stagedDir, { recursive: true });
-        const filePath = path7.join(stagedDir, "linker-staged.jsonl");
+        const stagedDir = path8.join(this.outputDir, "staged");
+        await fs7.mkdir(stagedDir, { recursive: true });
+        const filePath = path8.join(stagedDir, "linker-staged.jsonl");
         const lines = candidates.map(
           (c) => JSON.stringify({
             id: c.id,
@@ -3719,7 +3846,7 @@ var init_dist = __esm({
             nodeType: c.nodeType
           })
         );
-        await fs6.writeFile(filePath, lines.join("\n") + "\n");
+        await fs7.writeFile(filePath, lines.join("\n") + "\n");
       }
       /**
        * Apply heuristic patterns to content and return candidate extractions.
@@ -3821,6 +3948,14 @@ var init_dist = __esm({
         return { findings, driftScore, summary };
       }
     };
+    BUSINESS_NODE_TYPES = [
+      "business_concept",
+      "business_rule",
+      "business_process",
+      "business_term",
+      "business_metric",
+      "business_fact"
+    ];
     KnowledgeStagingAggregator = class {
       constructor(projectDir) {
         this.projectDir = projectDir;
@@ -3839,52 +3974,150 @@ var init_dist = __esm({
         if (deduplicated.length === 0) {
           return { staged: 0 };
         }
-        const stagedDir = path8.join(this.projectDir, ".harness", "knowledge", "staged");
-        await fs7.mkdir(stagedDir, { recursive: true });
+        const stagedDir = path9.join(this.projectDir, ".harness", "knowledge", "staged");
+        await fs8.mkdir(stagedDir, { recursive: true });
         const jsonl = deduplicated.map((entry) => JSON.stringify(entry)).join("\n") + "\n";
-        await fs7.writeFile(path8.join(stagedDir, "pipeline-staged.jsonl"), jsonl, "utf-8");
+        await fs8.writeFile(path9.join(stagedDir, "pipeline-staged.jsonl"), jsonl, "utf-8");
         return { staged: deduplicated.length };
       }
-      async generateGapReport(knowledgeDir) {
-        const domains = [];
+      async extractDocName(filePath) {
+        const raw = await fs8.readFile(filePath, "utf-8");
+        const fmMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+        const body = fmMatch ? fmMatch[1] : raw;
+        const titleMatch = body.match(/^#\s+(.+)$/m);
+        return titleMatch ? titleMatch[1].trim() : path9.basename(filePath, ".md");
+      }
+      async generateGapReport(knowledgeDir, store) {
+        const domainDocNames = /* @__PURE__ */ new Map();
+        const domainEntryCounts = /* @__PURE__ */ new Map();
         let totalEntries = 0;
         try {
-          const entries = await fs7.readdir(knowledgeDir, { withFileTypes: true });
+          const entries = await fs8.readdir(knowledgeDir, { withFileTypes: true });
           const domainDirs = entries.filter((e) => e.isDirectory());
           for (const dir of domainDirs) {
-            const domainPath = path8.join(knowledgeDir, dir.name);
-            const files = await fs7.readdir(domainPath);
+            const domainPath = path9.join(knowledgeDir, dir.name);
+            const files = await fs8.readdir(domainPath);
             const mdFiles = files.filter((f) => f.endsWith(".md"));
             const entryCount = mdFiles.length;
             totalEntries += entryCount;
-            domains.push({ domain: dir.name, entryCount });
+            domainEntryCounts.set(dir.name, entryCount);
+            if (store) {
+              const names = [];
+              for (const file of mdFiles) {
+                const name = await this.extractDocName(path9.join(domainPath, file));
+                names.push(name.toLowerCase().trim());
+              }
+              domainDocNames.set(dir.name, names);
+            }
           }
         } catch {
         }
+        if (!store) {
+          const domains2 = [];
+          for (const [domain, entryCount] of domainEntryCounts) {
+            domains2.push({ domain, entryCount, extractedCount: 0, gapCount: 0, gapEntries: [] });
+          }
+          return {
+            domains: domains2,
+            totalEntries,
+            totalExtracted: 0,
+            totalGaps: 0,
+            generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+        }
+        const extractedByDomain = /* @__PURE__ */ new Map();
+        for (const nodeType of BUSINESS_NODE_TYPES) {
+          const nodes = store.findNodes({ type: nodeType });
+          for (const node of nodes) {
+            const domain = node.metadata?.domain ?? "unknown";
+            const list = extractedByDomain.get(domain) ?? [];
+            list.push(node);
+            extractedByDomain.set(domain, list);
+          }
+        }
+        for (const [domain, nodes] of extractedByDomain) {
+          const seen = /* @__PURE__ */ new Set();
+          const deduped = nodes.filter((n) => {
+            const key = n.name.toLowerCase().trim();
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+          });
+          extractedByDomain.set(domain, deduped);
+        }
+        const allDomains = /* @__PURE__ */ new Set([...domainEntryCounts.keys(), ...extractedByDomain.keys()]);
+        const domains = [];
+        let totalExtracted = 0;
+        let totalGaps = 0;
+        for (const domain of allDomains) {
+          const entryCount = domainEntryCounts.get(domain) ?? 0;
+          const extractedNodes = extractedByDomain.get(domain) ?? [];
+          const extractedCount = extractedNodes.length;
+          totalExtracted += extractedCount;
+          const docNames = domainDocNames.get(domain) ?? [];
+          const gapEntries = [];
+          for (const node of extractedNodes) {
+            const normalizedName = node.name.toLowerCase().trim();
+            if (!docNames.includes(normalizedName)) {
+              gapEntries.push({
+                nodeId: node.id,
+                name: node.name,
+                nodeType: node.type,
+                source: node.metadata?.source ?? "unknown",
+                hasContent: Boolean(node.content && node.content.trim().length >= 10)
+              });
+            }
+          }
+          totalGaps += gapEntries.length;
+          domains.push({ domain, entryCount, extractedCount, gapCount: gapEntries.length, gapEntries });
+        }
         return {
           domains,
           totalEntries,
+          totalExtracted,
+          totalGaps,
           generatedAt: (/* @__PURE__ */ new Date()).toISOString()
         };
       }
       async writeGapReport(report) {
-        const gapsDir = path8.join(this.projectDir, ".harness", "knowledge");
-        await fs7.mkdir(gapsDir, { recursive: true });
+        const gapsDir = path9.join(this.projectDir, ".harness", "knowledge");
+        await fs8.mkdir(gapsDir, { recursive: true });
+        const hasDifferential = report.totalExtracted > 0;
         const lines = [
           "# Knowledge Gaps Report",
           "",
           `Generated: ${report.generatedAt}`,
           "",
           "## Coverage by Domain",
-          "",
-          "| Domain | Entries |",
-          "| ------ | ------- |"
+          ""
         ];
-        for (const domain of report.domains) {
-          lines.push(`| ${domain.domain} | ${domain.entryCount} |`);
+        if (hasDifferential) {
+          lines.push(
+            "| Domain | Documented | Extracted | Gaps |",
+            "| ------ | ---------- | --------- | ---- |"
+          );
+          for (const domain of report.domains) {
+            lines.push(
+              `| ${domain.domain} | ${domain.entryCount} | ${domain.extractedCount} | ${domain.gapCount} |`
+            );
+          }
+          lines.push(
+            "",
+            `## Summary`,
+            "",
+            `- **Total Documented:** ${report.totalEntries}`,
+            `- **Total Extracted:** ${report.totalExtracted}`,
+            `- **Total Gaps:** ${report.totalGaps}`,
+            ""
+          );
+        } else {
+          lines.push("| Domain | Entries |", "| ------ | ------- |");
+          for (const domain of report.domains) {
+            lines.push(`| ${domain.domain} | ${domain.entryCount} |`);
+          }
+          lines.push("", `## Total Entries: ${report.totalEntries}`, "");
         }
-        lines.push("", `## Total Entries: ${report.totalEntries}`, "");
-        await fs7.writeFile(path8.join(gapsDir, "gaps.md"), lines.join("\n"), "utf-8");
+        await fs8.writeFile(path9.join(gapsDir, "gaps.md"), lines.join("\n"), "utf-8");
       }
     };
     SKIP_DIRS2 = /* @__PURE__ */ new Set([
@@ -3946,7 +4179,7 @@ var init_dist = __esm({
         let nodesAdded = 0;
         let nodesUpdated = 0;
         let edgesAdded = 0;
-        await fs8.mkdir(outputDir, { recursive: true });
+        await fs9.mkdir(outputDir, { recursive: true });
         const files = await this.findSourceFiles(projectDir);
         const recordsByExtractor = /* @__PURE__ */ new Map();
         for (const ext of this.extractors) {
@@ -3955,17 +4188,17 @@ var init_dist = __esm({
         for (const filePath of files) {
           const language = detectLanguage(filePath);
           if (!language) continue;
-          const ext = path9.extname(filePath);
+          const ext = path10.extname(filePath);
           let content;
           try {
-            content = await fs8.readFile(filePath, "utf-8");
+            content = await fs9.readFile(filePath, "utf-8");
           } catch (err) {
             errors.push(
               `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`
             );
             continue;
           }
-          const relativePath = path9.relative(projectDir, filePath).replaceAll("\\", "/");
+          const relativePath = path10.relative(projectDir, filePath).replaceAll("\\", "/");
           for (const extractor2 of this.extractors) {
             if (!extractor2.supportedExtensions.includes(ext)) continue;
             try {
@@ -4002,9 +4235,9 @@ var init_dist = __esm({
       }
       /** Write extraction records to JSONL file. */
       async writeJsonl(records, outputDir, extractorName) {
-        const filePath = path9.join(outputDir, `${extractorName}.jsonl`);
+        const filePath = path10.join(outputDir, `${extractorName}.jsonl`);
         const lines = records.map((r) => JSON.stringify(r));
-        await fs8.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
+        await fs9.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
       }
       /** Create or update a graph node from an extraction record. */
       persistRecord(record, store) {
@@ -4076,12 +4309,12 @@ var init_dist = __esm({
         const results = [];
         let entries;
         try {
-          entries = await fs8.readdir(dir, { withFileTypes: true });
+          entries = await fs9.readdir(dir, { withFileTypes: true });
         } catch {
           return results;
         }
         for (const entry of entries) {
-          const fullPath = path9.join(dir, entry.name);
+          const fullPath = path10.join(dir, entry.name);
           if (entry.isDirectory() && !SKIP_DIRS2.has(entry.name)) {
             results.push(...await this.findSourceFiles(fullPath));
           } else if (entry.isFile() && detectLanguage(fullPath) !== void 0) {
@@ -5281,6 +5514,7 @@ var init_dist = __esm({
       "business_term",
       "business_concept",
       "business_metric",
+      "decision",
       "design_token",
       "design_constraint",
       "aesthetic_intent",
@@ -5361,7 +5595,161 @@ var init_dist = __esm({
         return parts[0] ?? "unclassified";
       }
     };
-    BUSINESS_NODE_TYPES = [
+    VALID_BUSINESS_TYPES = /* @__PURE__ */ new Set([
+      "business_rule",
+      "business_process",
+      "business_concept",
+      "business_term",
+      "business_metric"
+    ]);
+    DEFAULT_MAX_DOCS = 50;
+    MAX_COLLISION_SUFFIX = 10;
+    KnowledgeDocMaterializer = class {
+      constructor(store) {
+        this.store = store;
+      }
+      store;
+      async materialize(gapEntries, options) {
+        const maxDocs = options.maxDocs ?? DEFAULT_MAX_DOCS;
+        const created = [];
+        const skipped = [];
+        const createdNames = /* @__PURE__ */ new Set();
+        for (const entry of gapEntries) {
+          const resolved = await this.resolveEntry(
+            entry,
+            created.length,
+            maxDocs,
+            createdNames,
+            options
+          );
+          if ("reason" in resolved) {
+            skipped.push(resolved);
+            continue;
+          }
+          const { node, domain, domainDir, nameKey } = resolved;
+          await fs10.mkdir(domainDir, { recursive: true });
+          const basename10 = this.generateFilename(entry.name);
+          const filename = await this.resolveCollision(domainDir, basename10);
+          const content = this.formatDoc(node, domain);
+          const filePath = ["docs", "knowledge", domain, filename].join("/");
+          await fs10.writeFile(path11.join(options.projectDir, filePath), content, "utf-8");
+          createdNames.add(nameKey);
+          created.push({ filePath, nodeId: entry.nodeId, domain, name: entry.name });
+        }
+        return { created, skipped };
+      }
+      async resolveEntry(entry, createdCount, maxDocs, createdNames, options) {
+        if (!entry.hasContent) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "no_content" };
+        }
+        const node = this.store.getNode(entry.nodeId);
+        if (!node || !node.content || node.content.trim().length < 10) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "no_content" };
+        }
+        const domain = this.inferDomain(node);
+        if (!domain || /[/\\]|\.\.|\0/.test(domain)) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "no_domain" };
+        }
+        if (createdCount >= maxDocs) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "cap_reached" };
+        }
+        const domainDir = path11.join(options.projectDir, "docs", "knowledge", domain);
+        const nameKey = `${domain}:${entry.name.toLowerCase().trim()}`;
+        if (!createdNames.has(nameKey) && await this.hasExistingDoc(domainDir, entry.name)) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "already_documented" };
+        }
+        if (options.dryRun) {
+          return { nodeId: entry.nodeId, name: entry.name, reason: "dry_run" };
+        }
+        return { node, domain, domainDir, nameKey };
+      }
+      inferDomain(node) {
+        if (node.metadata?.domain && typeof node.metadata.domain === "string") {
+          return node.metadata.domain;
+        }
+        if (node.path) {
+          const pkgMatch = node.path.match(/^packages\/([^/]+)/);
+          if (pkgMatch) return pkgMatch[1];
+          const srcMatch = node.path.match(/^src\/([^/]+)/);
+          if (srcMatch) return srcMatch[1];
+        }
+        if (node.metadata?.source === "knowledge-linker" || node.metadata?.source === "connector") {
+          const connector = node.metadata.connectorName;
+          if (typeof connector === "string") return connector;
+          return "general";
+        }
+        return null;
+      }
+      generateFilename(name) {
+        const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+        return `${slug}.md`;
+      }
+      async resolveCollision(dir, basename10) {
+        const ext = path11.extname(basename10);
+        const stem = path11.basename(basename10, ext);
+        try {
+          await fs10.access(path11.join(dir, basename10));
+        } catch {
+          return basename10;
+        }
+        for (let i = 2; i <= MAX_COLLISION_SUFFIX; i++) {
+          const candidate = `${stem}-${i}${ext}`;
+          try {
+            await fs10.access(path11.join(dir, candidate));
+          } catch {
+            return candidate;
+          }
+        }
+        throw new Error(
+          `Cannot resolve filename collision for "${basename10}" after ${MAX_COLLISION_SUFFIX} attempts`
+        );
+      }
+      formatDoc(node, domain) {
+        const mappedType = this.mapNodeType(node);
+        const sanitize = (s) => s.replace(/[\n\r]/g, " ").replace(/:/g, "-");
+        const lines = ["---", `type: ${sanitize(mappedType)}`, `domain: ${sanitize(domain)}`];
+        const tags = node.metadata?.tags;
+        if (Array.isArray(tags) && tags.length > 0) {
+          lines.push(`tags: [${tags.map((t) => sanitize(String(t))).join(", ")}]`);
+        }
+        const related = node.metadata?.related;
+        if (Array.isArray(related) && related.length > 0) {
+          lines.push(`related: [${related.map((r) => sanitize(String(r))).join(", ")}]`);
+        }
+        const title = (node.name ?? "").replace(/[\n\r]/g, " ");
+        lines.push("---", "", `# ${title}`, "", node.content ?? "", "");
+        return lines.join("\n");
+      }
+      /** Check if a doc with a matching title already exists in the domain directory. */
+      async hasExistingDoc(domainDir, name) {
+        const normalizedName = name.toLowerCase().trim();
+        try {
+          const files = await fs10.readdir(domainDir);
+          for (const file of files) {
+            if (!file.endsWith(".md")) continue;
+            const raw = await fs10.readFile(path11.join(domainDir, file), "utf-8");
+            const fmMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+            const body = fmMatch ? fmMatch[1] : raw;
+            const titleMatch = body.match(/^#\s+(.+)$/m);
+            if (titleMatch && titleMatch[1].trim().toLowerCase() === normalizedName) {
+              return true;
+            }
+          }
+        } catch {
+        }
+        return false;
+      }
+      mapNodeType(node) {
+        if (VALID_BUSINESS_TYPES.has(node.type)) {
+          return node.type;
+        }
+        if (node.type === "business_fact") {
+          return "business_rule";
+        }
+        return "business_concept";
+      }
+    };
+    BUSINESS_NODE_TYPES2 = [
       "business_concept",
       "business_rule",
       "business_process",
@@ -5370,7 +5758,8 @@ var init_dist = __esm({
       "business_fact"
     ];
     SNAPSHOT_NODE_TYPES = [
-      ...BUSINESS_NODE_TYPES,
+      ...BUSINESS_NODE_TYPES2,
+      "decision",
       "design_token",
       "design_constraint",
       "aesthetic_intent",
@@ -5383,14 +5772,28 @@ var init_dist = __esm({
       store;
       async run(options) {
         const remediations = [];
+        const preSnapshot = this.buildSnapshot(options.domain);
         const extraction = await this.extract(options);
-        let driftResult = this.runReconciliation(options);
+        const postSnapshot = this.buildSnapshot(options.domain);
+        let driftResult = this.reconcile(preSnapshot, postSnapshot);
         const contradictions = new ContradictionDetector().detect(this.store);
         let gapReport = await this.detect(options);
         const coverage = new CoverageScorer().score(this.store);
-        const iterations = options.fix ? await this.runRemediationLoop(options, driftResult, gapReport, remediations) : 1;
+        let materialization;
+        let iterations = 1;
+        if (options.fix) {
+          const loopResult = await this.runRemediationLoop(
+            options,
+            driftResult,
+            gapReport,
+            remediations
+          );
+          iterations = loopResult.iterations;
+          materialization = loopResult.materialization;
+        }
         if (options.fix && iterations > 1) {
-          driftResult = this.runReconciliation(options);
+          const finalSnapshot = this.buildSnapshot(options.domain);
+          driftResult = this.reconcile(preSnapshot, finalSnapshot);
           gapReport = await this.detect(options);
         }
         await this.stageNewFindings(driftResult, options);
@@ -5401,35 +5804,48 @@ var init_dist = __esm({
           gapReport,
           remediations,
           contradictions,
-          coverage
+          coverage,
+          materialization
         );
       }
-      /** Run phases 1-2 (extract snapshot, reconcile) and return drift result. */
-      runReconciliation(options) {
-        const preSnapshot = this.buildSnapshot(options.domain);
-        const postSnapshot = this.buildSnapshot(options.domain);
-        return this.reconcile(preSnapshot, postSnapshot);
-      }
-      /** Run the remediation convergence loop; returns total iteration count. */
-      async runRemediationLoop(options, driftResult, _gapReport, remediations) {
+      /** Run the remediation convergence loop; returns iteration count and accumulated materialization. */
+      async runRemediationLoop(options, driftResult, gapReport, remediations) {
         const maxIterations = options.maxIterations ?? 5;
         let iterations = 1;
         let currentDrift = driftResult;
-        let previousFindingCount = currentDrift.findings.length;
+        let currentGapReport = gapReport;
+        let previousIssueCount = currentDrift.findings.length + currentGapReport.totalGaps;
+        let accumulatedMaterialization;
         while (iterations < maxIterations) {
-          if (currentDrift.findings.length === 0) break;
-          this.remediate(currentDrift, remediations, options);
+          if (currentDrift.findings.length === 0 && currentGapReport.totalGaps === 0) break;
+          const matResult = await this.remediate(currentDrift, remediations, options, currentGapReport);
+          if (matResult) {
+            if (!accumulatedMaterialization) {
+              accumulatedMaterialization = matResult;
+            } else {
+              accumulatedMaterialization = {
+                created: [...accumulatedMaterialization.created, ...matResult.created],
+                skipped: [...accumulatedMaterialization.skipped, ...matResult.skipped]
+              };
+            }
+          }
+          const preSnapshot = this.buildSnapshot(options.domain);
           await this.extract(options);
-          currentDrift = this.runReconciliation(options);
-          await this.detect(options);
+          const postSnapshot = this.buildSnapshot(options.domain);
+          currentDrift = this.reconcile(preSnapshot, postSnapshot);
+          currentGapReport = await this.detect(options);
           iterations++;
-          if (currentDrift.findings.length >= previousFindingCount) break;
-          previousFindingCount = currentDrift.findings.length;
+          const currentIssueCount = currentDrift.findings.length + currentGapReport.totalGaps;
+          if (currentIssueCount >= previousIssueCount) break;
+          previousIssueCount = currentIssueCount;
         }
-        return iterations;
+        return {
+          iterations,
+          ...accumulatedMaterialization ? { materialization: accumulatedMaterialization } : {}
+        };
       }
       /** Assemble the final pipeline result. */
-      buildResult(driftResult, iterations, extraction, gaps, remediations, contradictions, coverage) {
+      buildResult(driftResult, iterations, extraction, gaps, remediations, contradictions, coverage, materialization) {
         return {
           verdict: this.computeVerdict(driftResult),
           driftScore: driftResult.driftScore,
@@ -5439,13 +5855,14 @@ var init_dist = __esm({
           gaps,
           remediations,
           contradictions,
-          coverage
+          coverage,
+          ...materialization ? { materialization } : {}
         };
       }
       // ── Phase 1: EXTRACT ──────────────────────────────────────────────────────
       async extract(options) {
-        const extractedDir = path10.join(options.projectDir, ".harness", "knowledge", "extracted");
-        await fs9.mkdir(extractedDir, { recursive: true });
+        const extractedDir = path12.join(options.projectDir, ".harness", "knowledge", "extracted");
+        await fs11.mkdir(extractedDir, { recursive: true });
         const runner = createExtractionRunner();
         const extractionResult = await runner.run(options.projectDir, this.store, extractedDir);
         const diagramParser = new DiagramParser(this.store);
@@ -5459,7 +5876,7 @@ var init_dist = __esm({
           const imageResult = await imageExtractor.analyze(this.store, imagePaths);
           imageCount = imageResult.nodesAdded;
         }
-        const knowledgeDir = path10.join(options.projectDir, "docs", "knowledge");
+        const knowledgeDir = path12.join(options.projectDir, "docs", "knowledge");
         const bkIngestor = new BusinessKnowledgeIngestor(this.store);
         let bkResult;
         try {
@@ -5474,6 +5891,21 @@ var init_dist = __esm({
             durationMs: 0
           };
         }
+        const decisionsDir = path12.join(options.projectDir, "docs", "knowledge", "decisions");
+        const decisionIngestor = new DecisionIngestor(this.store);
+        let decisionResult;
+        try {
+          decisionResult = await decisionIngestor.ingest(decisionsDir);
+        } catch {
+          decisionResult = {
+            nodesAdded: 0,
+            nodesUpdated: 0,
+            edgesAdded: 0,
+            edgesUpdated: 0,
+            errors: [],
+            durationMs: 0
+          };
+        }
         const linker = new KnowledgeLinker(this.store, extractedDir);
         const linkResult = await linker.link();
         return {
@@ -5481,6 +5913,7 @@ var init_dist = __esm({
           diagrams: diagramResult.nodesAdded,
           linkerFacts: linkResult.factsCreated,
           businessKnowledge: bkResult.nodesAdded,
+          decisions: decisionResult.nodesAdded,
           images: imageCount
         };
       }
@@ -5507,14 +5940,14 @@ var init_dist = __esm({
       }
       // ── Phase 3: DETECT ───────────────────────────────────────────────────────
       async detect(options) {
-        const knowledgeDir = path10.join(options.projectDir, "docs", "knowledge");
+        const knowledgeDir = path12.join(options.projectDir, "docs", "knowledge");
         const aggregator = new KnowledgeStagingAggregator(options.projectDir);
-        const gapReport = await aggregator.generateGapReport(knowledgeDir);
+        const gapReport = await aggregator.generateGapReport(knowledgeDir, this.store);
         await aggregator.writeGapReport(gapReport);
         return gapReport;
       }
       // ── Phase 4: REMEDIATE ────────────────────────────────────────────────────
-      remediate(driftResult, remediations, options) {
+      async remediate(driftResult, remediations, options, gapReport) {
         for (const finding of driftResult.findings) {
           switch (finding.classification) {
             case "stale":
@@ -5532,6 +5965,22 @@ var init_dist = __esm({
               break;
           }
         }
+        if (!options.ci) {
+          const allGapEntries = gapReport.domains.flatMap((d) => d.gapEntries);
+          const materializable = allGapEntries.filter((e) => e.hasContent);
+          if (materializable.length > 0) {
+            const materializer = new KnowledgeDocMaterializer(this.store);
+            const matResult = await materializer.materialize(materializable, {
+              projectDir: options.projectDir,
+              dryRun: false
+            });
+            for (const doc of matResult.created) {
+              remediations.push(`created doc: ${doc.filePath}`);
+            }
+            return matResult;
+          }
+        }
+        return void 0;
       }
       async stageNewFindings(driftResult, options) {
         const newFindings = driftResult.findings.filter((f) => f.classification === "new");
@@ -5564,7 +6013,7 @@ var init_dist = __esm({
         return "fail";
       }
     };
-    CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
     RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     SANITIZE_RULES = [
       // Strip XML/HTML-like instruction tags that could be interpreted as system prompts
@@ -5591,7 +6040,7 @@ var init_dist = __esm({
     SyncManager = class {
       constructor(store, graphDir) {
         this.store = store;
-        this.metadataPath = path11.join(graphDir, "sync-metadata.json");
+        this.metadataPath = path13.join(graphDir, "sync-metadata.json");
       }
       store;
       registrations = /* @__PURE__ */ new Map();
@@ -5656,15 +6105,15 @@ var init_dist = __esm({
       }
       async loadMetadata() {
         try {
-          const raw = await fs10.readFile(this.metadataPath, "utf-8");
+          const raw = await fs12.readFile(this.metadataPath, "utf-8");
           return JSON.parse(raw);
         } catch {
           return { connectors: {} };
         }
       }
       async saveMetadata(metadata) {
-        await fs10.mkdir(path11.dirname(this.metadataPath), { recursive: true });
-        await fs10.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+        await fs12.mkdir(path13.dirname(this.metadataPath), { recursive: true });
+        await fs12.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
       }
     };
     SUMMARIZE_PROMPT = `Summarize the following content to fit within the specified length.
@@ -5702,6 +6151,14 @@ Content to summarize:
             start
           );
         }
+        try {
+          const parsed = new URL(baseUrl);
+          if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+            return buildIngestResult(0, 0, [`${baseUrlEnv} must use HTTPS`], start);
+          }
+        } catch {
+          return buildIngestResult(0, 0, [`${baseUrlEnv} is not a valid URL`], start);
+        }
         const jql = buildJql(config);
         const headers = { Authorization: `Basic ${apiKey}`, "Content-Type": "application/json" };
         try {
@@ -5955,6 +6412,14 @@ ${replyLines.join("\n")}`;
         }
         const baseUrlEnv = config.baseUrlEnv ?? "CONFLUENCE_BASE_URL";
         const baseUrl = process.env[baseUrlEnv] ?? "";
+        try {
+          const parsed = new URL(baseUrl);
+          if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+            return missingApiKeyResult(`${baseUrlEnv} must use HTTPS`, start);
+          }
+        } catch {
+          return missingApiKeyResult(`${baseUrlEnv} is not a valid URL`, start);
+        }
         const spaceKey = config.spaceKey ?? "";
         const counts = await this.fetchAllPagesHandled(
           store,
@@ -6486,7 +6951,7 @@ ${replyLines.join("\n")}`;
         return 0;
       }
     };
-    CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES6 = ["file", "function", "class", "method", "interface", "variable"];
     GraphEntropyAdapter = class {
       constructor(store) {
         this.store = store;
@@ -6566,7 +7031,7 @@ ${replyLines.join("\n")}`;
       }
       findEntryPoints() {
         const entryPoints = [];
-        for (const nodeType of CODE_NODE_TYPES5) {
+        for (const nodeType of CODE_NODE_TYPES6) {
           const nodes = this.store.findNodes({ type: nodeType });
           for (const node of nodes) {
             const isIndexFile = nodeType === "file" && node.name === "index.ts";
@@ -6602,7 +7067,7 @@ ${replyLines.join("\n")}`;
       }
       collectUnreachableNodes(visited) {
         const unreachableNodes = [];
-        for (const nodeType of CODE_NODE_TYPES5) {
+        for (const nodeType of CODE_NODE_TYPES6) {
           const nodes = this.store.findNodes({ type: nodeType });
           for (const node of nodes) {
             if (!visited.has(node.id)) {
@@ -7419,9 +7884,9 @@ ${replyLines.join("\n")}`;
       extractPaths(trimmed, add) {
         const consumed = /* @__PURE__ */ new Set();
         for (const match of trimmed.matchAll(FILE_PATH_RE)) {
-          const path13 = match[0];
-          add(path13);
-          consumed.add(path13);
+          const path15 = match[0];
+          add(path15);
+          consumed.add(path15);
         }
         return consumed;
       }
@@ -7491,8 +7956,8 @@ ${replyLines.join("\n")}`;
           if (isPathLike && node.path.includes(raw)) {
             return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
           }
-          const basename7 = node.path.split("/").pop() ?? "";
-          if (basename7.includes(raw)) {
+          const basename10 = node.path.split("/").pop() ?? "";
+          if (basename10.includes(raw)) {
             return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
           }
           if (raw.length >= 4 && node.path.includes(raw)) {
@@ -7569,13 +8034,13 @@ ${replyLines.join("\n")}`;
         const context = Array.isArray(d?.context) ? d.context : [];
         const firstEntity = entities[0];
         const nodeType = firstEntity?.node.type ?? "node";
-        const path13 = firstEntity?.node.path ?? "unknown";
+        const path15 = firstEntity?.node.path ?? "unknown";
         let neighborCount = 0;
         const firstContext = context[0];
         if (firstContext && Array.isArray(firstContext.nodes)) {
           neighborCount = firstContext.nodes.length;
         }
-        return `**${entityName}** is a ${nodeType} at \`${path13}\`. Connected to ${neighborCount} nodes.`;
+        return `**${entityName}** is a ${nodeType} at \`${path15}\`. Connected to ${neighborCount} nodes.`;
       }
       formatAnomaly(data) {
         const d = data;
@@ -7845,7 +8310,7 @@ ${replyLines.join("\n")}`;
       debug: ["failure", "learning", "function", "method"],
       plan: ["adr", "document", "module", "layer"]
     };
-    CODE_NODE_TYPES6 = /* @__PURE__ */ new Set([
+    CODE_NODE_TYPES7 = /* @__PURE__ */ new Set([
       "file",
       "function",
       "class",
@@ -8055,7 +8520,7 @@ ${replyLines.join("\n")}`;
        */
       checkCoverage() {
         const codeNodes = [];
-        for (const type of CODE_NODE_TYPES6) {
+        for (const type of CODE_NODE_TYPES7) {
           codeNodes.push(...this.store.findNodes({ type }));
         }
         const documented = [];
@@ -8200,8 +8665,8 @@ ${replyLines.join("\n")}`;
       async ingestAll(designDir) {
         const start = Date.now();
         const [tokensResult, intentResult] = await Promise.all([
-          this.ingestTokens(path12.join(designDir, "tokens.json")),
-          this.ingestDesignIntent(path12.join(designDir, "DESIGN.md"))
+          this.ingestTokens(path14.join(designDir, "tokens.json")),
+          this.ingestDesignIntent(path14.join(designDir, "DESIGN.md"))
         ]);
         const merged = mergeResults(tokensResult, intentResult);
         return { ...merged, durationMs: Date.now() - start };
@@ -8431,10 +8896,10 @@ ${replyLines.join("\n")}`;
             includeTypes: ["file"]
           });
           for (const n of queryResult.nodes) {
-            const path13 = n.path ?? n.id.replace(/^file:/, "");
-            if (!fileSet.has(path13)) {
-              if (!result.has(path13)) {
-                result.set(path13, file);
+            const path15 = n.path ?? n.id.replace(/^file:/, "");
+            if (!fileSet.has(path15)) {
+              if (!result.has(path15)) {
+                result.set(path15, file);
               }
             }
           }
@@ -8807,7 +9272,7 @@ ${replyLines.join("\n")}`;
         return parts.join(" ");
       }
     };
-    VERSION = "0.4.3";
+    VERSION = "0.6.0";
   }
 });
 
@@ -8834,6 +9299,7 @@ export {
   TopologicalLinker,
   KnowledgeIngestor,
   BusinessKnowledgeIngestor,
+  DecisionIngestor,
   RequirementIngestor,
   MermaidParser,
   D2Parser,
@@ -8852,6 +9318,7 @@ export {
   ImageAnalysisExtractor,
   ContradictionDetector,
   CoverageScorer,
+  KnowledgeDocMaterializer,
   KnowledgePipelineRunner,
   linkToCode,
   SyncManager,