@harness-engineering/graph 0.3.4 → 0.4.0

package/dist/index.js

@@ -59,6 +59,7 @@ __export(index_exports, {
   KnowledgeIngestor: () => KnowledgeIngestor,
   NODE_TYPES: () => NODE_TYPES,
   OBSERVABILITY_TYPES: () => OBSERVABILITY_TYPES,
+  RequirementIngestor: () => RequirementIngestor,
   ResponseFormatter: () => ResponseFormatter,
   SlackConnector: () => SlackConnector,
   SyncManager: () => SyncManager,
@@ -71,6 +72,7 @@ __export(index_exports, {
   linkToCode: () => linkToCode,
   loadGraph: () => loadGraph,
   project: () => project,
+  queryTraceability: () => queryTraceability,
   saveGraph: () => saveGraph
 });
 module.exports = __toCommonJS(index_exports);
@@ -112,7 +114,9 @@ var NODE_TYPES = [
   // Design
   "design_token",
   "aesthetic_intent",
-  "design_constraint"
+  "design_constraint",
+  // Traceability
+  "requirement"
 ];
 var EDGE_TYPES = [
   // Code relationships
@@ -141,7 +145,11 @@ var EDGE_TYPES = [
   "uses_token",
   "declares_intent",
   "violates_design",
-  "platform_binding"
+  "platform_binding",
+  // Traceability relationships
+  "requires",
+  "verified_by",
+  "tested_by"
 ];
 var OBSERVABILITY_TYPES = /* @__PURE__ */ new Set(["span", "metric", "log"]);
 var CURRENT_SCHEMA_VERSION = 1;
@@ -171,9 +179,6 @@ var GraphEdgeSchema = import_zod.z.object({
   metadata: import_zod.z.record(import_zod.z.unknown()).optional()
 });
 
-// src/store/GraphStore.ts
-var import_lokijs = __toESM(require("lokijs"));
-
 // src/store/Serializer.ts
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
@@ -218,28 +223,38 @@ function safeMerge(target, source) {
     }
   }
 }
-var GraphStore = class {
-  db;
-  nodes;
-  edges;
-  constructor() {
-    this.db = new import_lokijs.default("graph.db");
-    this.nodes = this.db.addCollection("nodes", {
-      unique: ["id"],
-      indices: ["type", "name"]
-    });
-    this.edges = this.db.addCollection("edges", {
-      indices: ["from", "to", "type"]
-    });
+function edgeKey(from, to, type) {
+  return `${from}\0${to}\0${type}`;
+}
+function addToIndex(index, key, edge) {
+  const list = index.get(key);
+  if (list) {
+    list.push(edge);
+  } else {
+    index.set(key, [edge]);
   }
+}
+function removeFromIndex(index, key, edge) {
+  const list = index.get(key);
+  if (!list) return;
+  const idx = list.indexOf(edge);
+  if (idx !== -1) list.splice(idx, 1);
+  if (list.length === 0) index.delete(key);
+}
+var GraphStore = class {
+  nodeMap = /* @__PURE__ */ new Map();
+  edgeMap = /* @__PURE__ */ new Map();
+  // keyed by from\0to\0type
+  edgesByFrom = /* @__PURE__ */ new Map();
+  edgesByTo = /* @__PURE__ */ new Map();
+  edgesByType = /* @__PURE__ */ new Map();
   // --- Node operations ---
   addNode(node) {
-    const existing = this.nodes.by("id", node.id);
+    const existing = this.nodeMap.get(node.id);
     if (existing) {
       safeMerge(existing, node);
-      this.nodes.update(existing);
     } else {
-      this.nodes.insert({ ...node });
+      this.nodeMap.set(node.id, { ...node });
     }
   }
   batchAddNodes(nodes) {
@@ -248,44 +263,44 @@ var GraphStore = class {
     }
   }
   getNode(id) {
-    const doc = this.nodes.by("id", id);
-    if (!doc) return null;
-    return this.stripLokiMeta(doc);
+    const node = this.nodeMap.get(id);
+    if (!node) return null;
+    return { ...node };
   }
   findNodes(query) {
-    const lokiQuery = {};
-    if (query.type !== void 0) lokiQuery["type"] = query.type;
-    if (query.name !== void 0) lokiQuery["name"] = query.name;
-    if (query.path !== void 0) lokiQuery["path"] = query.path;
-    return this.nodes.find(lokiQuery).map((doc) => this.stripLokiMeta(doc));
+    const results = [];
+    for (const node of this.nodeMap.values()) {
+      if (query.type !== void 0 && node.type !== query.type) continue;
+      if (query.name !== void 0 && node.name !== query.name) continue;
+      if (query.path !== void 0 && node.path !== query.path) continue;
+      results.push({ ...node });
+    }
+    return results;
   }
   removeNode(id) {
-    const doc = this.nodes.by("id", id);
-    if (doc) {
-      this.nodes.remove(doc);
-    }
-    const edgesToRemove = this.edges.find({
-      $or: [{ from: id }, { to: id }]
-    });
+    this.nodeMap.delete(id);
+    const fromEdges = this.edgesByFrom.get(id) ?? [];
+    const toEdges = this.edgesByTo.get(id) ?? [];
+    const edgesToRemove = /* @__PURE__ */ new Set([...fromEdges, ...toEdges]);
     for (const edge of edgesToRemove) {
-      this.edges.remove(edge);
+      this.removeEdgeInternal(edge);
     }
   }
   // --- Edge operations ---
   addEdge(edge) {
-    const existing = this.edges.findOne({
-      from: edge.from,
-      to: edge.to,
-      type: edge.type
-    });
+    const key = edgeKey(edge.from, edge.to, edge.type);
+    const existing = this.edgeMap.get(key);
     if (existing) {
       if (edge.metadata) {
         safeMerge(existing, edge);
-        this.edges.update(existing);
       }
       return;
     }
-    this.edges.insert({ ...edge });
+    const copy = { ...edge };
+    this.edgeMap.set(key, copy);
+    addToIndex(this.edgesByFrom, edge.from, copy);
+    addToIndex(this.edgesByTo, edge.to, copy);
+    addToIndex(this.edgesByType, edge.type, copy);
   }
   batchAddEdges(edges) {
     for (const edge of edges) {
@@ -293,22 +308,38 @@ var GraphStore = class {
     }
   }
   getEdges(query) {
-    const lokiQuery = {};
-    if (query.from !== void 0) lokiQuery["from"] = query.from;
-    if (query.to !== void 0) lokiQuery["to"] = query.to;
-    if (query.type !== void 0) lokiQuery["type"] = query.type;
-    return this.edges.find(lokiQuery).map((doc) => this.stripLokiMeta(doc));
+    let candidates;
+    if (query.from !== void 0 && query.to !== void 0 && query.type !== void 0) {
+      const edge = this.edgeMap.get(edgeKey(query.from, query.to, query.type));
+      return edge ? [{ ...edge }] : [];
+    } else if (query.from !== void 0) {
+      candidates = this.edgesByFrom.get(query.from) ?? [];
+    } else if (query.to !== void 0) {
+      candidates = this.edgesByTo.get(query.to) ?? [];
+    } else if (query.type !== void 0) {
+      candidates = this.edgesByType.get(query.type) ?? [];
+    } else {
+      candidates = this.edgeMap.values();
+    }
+    const results = [];
+    for (const edge of candidates) {
+      if (query.from !== void 0 && edge.from !== query.from) continue;
+      if (query.to !== void 0 && edge.to !== query.to) continue;
+      if (query.type !== void 0 && edge.type !== query.type) continue;
+      results.push({ ...edge });
+    }
+    return results;
   }
   getNeighbors(nodeId, direction = "both") {
     const neighborIds = /* @__PURE__ */ new Set();
     if (direction === "outbound" || direction === "both") {
-      const outEdges = this.edges.find({ from: nodeId });
+      const outEdges = this.edgesByFrom.get(nodeId) ?? [];
       for (const edge of outEdges) {
         neighborIds.add(edge.to);
       }
     }
     if (direction === "inbound" || direction === "both") {
-      const inEdges = this.edges.find({ to: nodeId });
+      const inEdges = this.edgesByTo.get(nodeId) ?? [];
       for (const edge of inEdges) {
         neighborIds.add(edge.from);
       }
@@ -322,20 +353,23 @@ var GraphStore = class {
   }
   // --- Counts ---
   get nodeCount() {
-    return this.nodes.count();
+    return this.nodeMap.size;
   }
   get edgeCount() {
-    return this.edges.count();
+    return this.edgeMap.size;
   }
   // --- Clear ---
   clear() {
-    this.nodes.clear();
-    this.edges.clear();
+    this.nodeMap.clear();
+    this.edgeMap.clear();
+    this.edgesByFrom.clear();
+    this.edgesByTo.clear();
+    this.edgesByType.clear();
   }
   // --- Persistence ---
   async save(dirPath) {
-    const allNodes = this.nodes.find().map((doc) => this.stripLokiMeta(doc));
-    const allEdges = this.edges.find().map((doc) => this.stripLokiMeta(doc));
+    const allNodes = Array.from(this.nodeMap.values()).map((n) => ({ ...n }));
+    const allEdges = Array.from(this.edgeMap.values()).map((e) => ({ ...e }));
     await saveGraph(dirPath, allNodes, allEdges);
   }
   async load(dirPath) {
@@ -343,17 +377,25 @@ var GraphStore = class {
     if (!data) return false;
     this.clear();
     for (const node of data.nodes) {
-      this.nodes.insert({ ...node });
+      this.nodeMap.set(node.id, { ...node });
     }
     for (const edge of data.edges) {
-      this.edges.insert({ ...edge });
+      const copy = { ...edge };
+      const key = edgeKey(edge.from, edge.to, edge.type);
+      this.edgeMap.set(key, copy);
+      addToIndex(this.edgesByFrom, edge.from, copy);
+      addToIndex(this.edgesByTo, edge.to, copy);
+      addToIndex(this.edgesByType, edge.type, copy);
     }
     return true;
   }
   // --- Internal ---
-  stripLokiMeta(doc) {
-    const { $loki: _, meta: _meta, ...rest } = doc;
-    return rest;
+  removeEdgeInternal(edge) {
+    const key = edgeKey(edge.from, edge.to, edge.type);
+    this.edgeMap.delete(key);
+    removeFromIndex(this.edgesByFrom, edge.from, edge);
+    removeFromIndex(this.edgesByTo, edge.to, edge);
+    removeFromIndex(this.edgesByType, edge.type, edge);
   }
 };
 
@@ -434,11 +476,11 @@ var VectorStore = class _VectorStore {
 };
 
 // src/query/ContextQL.ts
-function edgeKey(e) {
+function edgeKey2(e) {
   return `${e.from}|${e.to}|${e.type}`;
 }
 function addEdge(state, edge) {
-  const key = edgeKey(edge);
+  const key = edgeKey2(edge);
   if (!state.edgeSet.has(key)) {
     state.edgeSet.add(key);
     state.resultEdges.push(edge);
@@ -618,6 +660,7 @@ var CodeIngestor = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   async ingest(rootDir) {
     const start = Date.now();
     const errors = [];
@@ -640,6 +683,7 @@ var CodeIngestor = class {
       this.store.addEdge(edge);
       edgesAdded++;
     }
+    edgesAdded += this.extractReqAnnotations(fileContents, rootDir);
     return {
       nodesAdded,
       nodesUpdated: 0,
@@ -998,6 +1042,48 @@ var CodeIngestor = class {
     if (/\.jsx?$/.test(filePath)) return "javascript";
     return "unknown";
   }
+  /**
+   * Scan file contents for @req annotations and create verified_by edges
+   * linking requirement nodes to the annotated files.
+   * Format: // @req <feature-name>#<index>
+   */
+  extractReqAnnotations(fileContents, rootDir) {
+    const REQ_TAG = /\/\/\s*@req\s+([\w-]+)#(\d+)/g;
+    const reqNodes = this.store.findNodes({ type: "requirement" });
+    let edgesAdded = 0;
+    for (const [filePath, content] of fileContents) {
+      let match;
+      REQ_TAG.lastIndex = 0;
+      while ((match = REQ_TAG.exec(content)) !== null) {
+        const featureName = match[1];
+        const reqIndex = parseInt(match[2], 10);
+        const reqNode = reqNodes.find(
+          (n) => n.metadata.featureName === featureName && n.metadata.index === reqIndex
+        );
+        if (!reqNode) {
+          console.warn(
+            `@req annotation references non-existent requirement: ${featureName}#${reqIndex} in ${filePath}`
+          );
+          continue;
+        }
+        const relPath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+        const fileNodeId = `file:${relPath}`;
+        this.store.addEdge({
+          from: reqNode.id,
+          to: fileNodeId,
+          type: "verified_by",
+          confidence: 1,
+          metadata: {
+            method: "annotation",
+            tag: `@req ${featureName}#${reqIndex}`,
+            confidence: 1
+          }
+        });
+        edgesAdded++;
+      }
+    }
+    return edgesAdded;
+  }
 };
 
 // src/ingest/GitIngestor.ts
@@ -1009,6 +1095,8 @@ var GitIngestor = class {
     this.store = store;
     this.gitRunner = gitRunner;
   }
+  store;
+  gitRunner;
   async ingest(rootDir) {
     const start = Date.now();
     const errors = [];
@@ -1188,6 +1276,7 @@ var TopologicalLinker = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   link() {
     let edgesAdded = 0;
     const files = this.store.findNodes({ type: "file" });
@@ -1285,6 +1374,7 @@ var KnowledgeIngestor = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   async ingestADRs(adrDir) {
     const start = Date.now();
     const errors = [];
@@ -1470,8 +1560,218 @@ var KnowledgeIngestor = class {
   }
 };
 
-// src/ingest/connectors/ConnectorUtils.ts
+// src/ingest/RequirementIngestor.ts
+var fs3 = __toESM(require("fs/promises"));
+var path4 = __toESM(require("path"));
+var REQUIREMENT_SECTIONS = [
+  "Observable Truths",
+  "Success Criteria",
+  "Acceptance Criteria"
+];
+var SECTION_HEADING_RE = /^#{2,3}\s+(.+)$/;
+var NUMBERED_ITEM_RE = /^\s*(\d+)\.\s+(.+)$/;
+function detectEarsPattern(text) {
+  const lower = text.toLowerCase();
+  if (/^if\b.+\bthen\b.+\bshall not\b/.test(lower)) return "unwanted";
+  if (/^when\b/.test(lower)) return "event-driven";
+  if (/^while\b/.test(lower)) return "state-driven";
+  if (/^where\b/.test(lower)) return "optional";
+  if (/^the\s+\w+\s+shall\b/.test(lower)) return "ubiquitous";
+  return void 0;
+}
 var CODE_NODE_TYPES2 = ["file", "function", "class", "method", "interface", "variable"];
+var RequirementIngestor = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  /**
+   * Scan a specs directory for `<feature>/proposal.md` files,
+   * extract numbered requirements from recognized sections,
+   * and create requirement nodes with convention-based edges.
+   */
+  async ingestSpecs(specsDir) {
+    const start = Date.now();
+    const errors = [];
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    let featureDirs;
+    try {
+      const entries = await fs3.readdir(specsDir, { withFileTypes: true });
+      featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path4.join(specsDir, e.name));
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    for (const featureDir of featureDirs) {
+      const featureName = path4.basename(featureDir);
+      const specPath = path4.join(featureDir, "proposal.md");
+      let content;
+      try {
+        content = await fs3.readFile(specPath, "utf-8");
+      } catch {
+        continue;
+      }
+      try {
+        const specHash = hash(specPath);
+        const specNodeId = `file:${specPath}`;
+        this.store.addNode({
+          id: specNodeId,
+          type: "document",
+          name: path4.basename(specPath),
+          path: specPath,
+          metadata: { featureName }
+        });
+        const requirements = this.extractRequirements(content, specPath, specHash, featureName);
+        for (const req of requirements) {
+          this.store.addNode(req.node);
+          nodesAdded++;
+          this.store.addEdge({
+            from: req.node.id,
+            to: specNodeId,
+            type: "specifies"
+          });
+          edgesAdded++;
+          edgesAdded += this.linkByPathPattern(req.node.id, featureName);
+          edgesAdded += this.linkByKeywordOverlap(req.node.id, req.node.name);
+        }
+      } catch (err) {
+        errors.push(`${specPath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Parse markdown content and extract numbered items from recognized sections.
+   */
+  extractRequirements(content, specPath, specHash, featureName) {
+    const lines = content.split("\n");
+    const results = [];
+    let currentSection;
+    let inRequirementSection = false;
+    let globalIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(SECTION_HEADING_RE);
+      if (headingMatch) {
+        const heading = headingMatch[1].trim();
+        const isReqSection = REQUIREMENT_SECTIONS.some(
+          (s) => heading.toLowerCase() === s.toLowerCase()
+        );
+        if (isReqSection) {
+          currentSection = heading;
+          inRequirementSection = true;
+        } else {
+          inRequirementSection = false;
+        }
+        continue;
+      }
+      if (!inRequirementSection) continue;
+      const itemMatch = line.match(NUMBERED_ITEM_RE);
+      if (!itemMatch) continue;
+      const index = parseInt(itemMatch[1], 10);
+      const text = itemMatch[2].trim();
+      const rawText = line.trim();
+      const lineNumber = i + 1;
+      globalIndex++;
+      const nodeId = `req:${specHash}:${globalIndex}`;
+      const earsPattern = detectEarsPattern(text);
+      results.push({
+        node: {
+          id: nodeId,
+          type: "requirement",
+          name: text,
+          path: specPath,
+          location: {
+            fileId: `file:${specPath}`,
+            startLine: lineNumber,
+            endLine: lineNumber
+          },
+          metadata: {
+            specPath,
+            index,
+            section: currentSection,
+            rawText,
+            earsPattern,
+            featureName
+          }
+        }
+      });
+    }
+    return results;
+  }
+  /**
+   * Convention-based linking: match requirement to code/test files
+   * by feature name in their path.
+   */
+  linkByPathPattern(reqId, featureName) {
+    let count = 0;
+    const fileNodes = this.store.findNodes({ type: "file" });
+    for (const node of fileNodes) {
+      if (!node.path) continue;
+      const normalizedPath = node.path.replace(/\\/g, "/");
+      const isCodeMatch = normalizedPath.includes("packages/") && path4.basename(normalizedPath).includes(featureName);
+      const isTestMatch = normalizedPath.includes("/tests/") && // platform-safe
+      path4.basename(normalizedPath).includes(featureName);
+      if (isCodeMatch && !isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "requires",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      } else if (isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "verified_by",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Convention-based linking: match requirement text to code nodes
+   * by keyword overlap (function/class names appearing in requirement text).
+   */
+  linkByKeywordOverlap(reqId, reqText) {
+    let count = 0;
+    for (const nodeType of CODE_NODE_TYPES2) {
+      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(reqText)) {
+          const edgeType = node.path && node.path.replace(/\\/g, "/").includes("/tests/") ? "verified_by" : "requires";
+          this.store.addEdge({
+            from: reqId,
+            to: node.id,
+            type: edgeType,
+            confidence: 0.6,
+            metadata: { method: "convention", matchReason: "keyword-overlap" }
+          });
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+};
+
+// src/ingest/connectors/ConnectorUtils.ts
+var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
 var SANITIZE_RULES = [
   // Strip XML/HTML-like instruction tags that could be interpreted as system prompts
   {
@@ -1506,7 +1806,7 @@ function sanitizeExternalText(text, maxLength = 2e3) {
 }
 function linkToCode(store, content, sourceNodeId, edgeType, options) {
   let edgesCreated = 0;
-  for (const type of CODE_NODE_TYPES2) {
+  for (const type of CODE_NODE_TYPES3) {
     const nodes = store.findNodes({ type });
     for (const node of nodes) {
       if (node.name.length < 3) continue;
@@ -1526,13 +1826,14 @@ function linkToCode(store, content, sourceNodeId, edgeType, options) {
 }
 
 // src/ingest/connectors/SyncManager.ts
-var fs3 = __toESM(require("fs/promises"));
-var path4 = __toESM(require("path"));
+var fs4 = __toESM(require("fs/promises"));
+var path5 = __toESM(require("path"));
 var SyncManager = class {
   constructor(store, graphDir) {
     this.store = store;
-    this.metadataPath = path4.join(graphDir, "sync-metadata.json");
+    this.metadataPath = path5.join(graphDir, "sync-metadata.json");
   }
+  store;
   registrations = /* @__PURE__ */ new Map();
   metadataPath;
   registerConnector(connector, config) {
@@ -1585,15 +1886,15 @@ var SyncManager = class {
   }
   async loadMetadata() {
     try {
-      const raw = await fs3.readFile(this.metadataPath, "utf-8");
+      const raw = await fs4.readFile(this.metadataPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { connectors: {} };
     }
   }
   async saveMetadata(metadata) {
-    await fs3.mkdir(path4.dirname(this.metadataPath), { recursive: true });
-    await fs3.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    await fs4.mkdir(path5.dirname(this.metadataPath), { recursive: true });
+    await fs4.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
   }
 };
 
@@ -2122,11 +2423,12 @@ var FusionLayer = class {
 };
 
 // src/entropy/GraphEntropyAdapter.ts
-var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
 var GraphEntropyAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   /**
    * Find all `documents` edges and classify them as stale or missing-target.
    *
@@ -2188,7 +2490,7 @@ var GraphEntropyAdapter = class {
   }
   findEntryPoints() {
     const entryPoints = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         const isIndexFile = nodeType === "file" && node.name === "index.ts";
@@ -2224,7 +2526,7 @@ var GraphEntropyAdapter = class {
   }
   collectUnreachableNodes(visited) {
     const unreachableNodes = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         if (!visited.has(node.id)) {
@@ -2267,6 +2569,7 @@ var GraphComplexityAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   /**
    * Compute complexity hotspots by combining cyclomatic complexity with change frequency.
    *
@@ -2354,6 +2657,7 @@ var GraphCouplingAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   /**
    * Compute coupling data for all file nodes in the graph.
    *
@@ -2423,6 +2727,7 @@ var GraphAnomalyAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   detect(options) {
     const threshold = options?.threshold != null && options.threshold > 0 ? options.threshold : DEFAULT_THRESHOLD;
     const requestedMetrics = options?.metrics ?? [...DEFAULT_METRICS];
@@ -3041,9 +3346,9 @@ var EntityExtractor = class {
     }
     const pathConsumed = /* @__PURE__ */ new Set();
     for (const match of trimmed.matchAll(FILE_PATH_RE)) {
-      const path6 = match[0];
-      add(path6);
-      pathConsumed.add(path6);
+      const path7 = match[0];
+      add(path7);
+      pathConsumed.add(path7);
     }
     const allConsumed = buildConsumedSet(quotedConsumed, casingConsumed, pathConsumed);
     const words = trimmed.split(/\s+/);
@@ -3114,8 +3419,8 @@ var EntityResolver = class {
       if (isPathLike && node.path.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
-      const basename4 = node.path.split("/").pop() ?? "";
-      if (basename4.includes(raw)) {
+      const basename5 = node.path.split("/").pop() ?? "";
+      if (basename5.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
       if (raw.length >= 4 && node.path.includes(raw)) {
@@ -3190,13 +3495,13 @@ var ResponseFormatter = class {
     const context = Array.isArray(d?.context) ? d.context : [];
     const firstEntity = entities[0];
     const nodeType = firstEntity?.node.type ?? "node";
-    const path6 = firstEntity?.node.path ?? "unknown";
+    const path7 = 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 \`${path6}\`. Connected to ${neighborCount} nodes.`;
+    return `**${entityName}** is a ${nodeType} at \`${path7}\`. Connected to ${neighborCount} nodes.`;
   }
   formatAnomaly(data) {
     const d = data;
@@ -3337,7 +3642,7 @@ var PHASE_NODE_TYPES = {
   debug: ["failure", "learning", "function", "method"],
   plan: ["adr", "document", "module", "layer"]
 };
-var CODE_NODE_TYPES4 = /* @__PURE__ */ new Set([
+var CODE_NODE_TYPES5 = /* @__PURE__ */ new Set([
   "file",
   "function",
   "class",
@@ -3552,7 +3857,7 @@ var Assembler = class {
    */
   checkCoverage() {
     const codeNodes = [];
-    for (const type of CODE_NODE_TYPES4) {
+    for (const type of CODE_NODE_TYPES5) {
       codeNodes.push(...this.store.findNodes({ type }));
     }
     const documented = [];
@@ -3576,6 +3881,89 @@ var Assembler = class {
   }
 };
 
+// src/query/Traceability.ts
+function queryTraceability(store, options) {
+  const allRequirements = store.findNodes({ type: "requirement" });
+  const filtered = allRequirements.filter((node) => {
+    if (options?.specPath && node.metadata?.specPath !== options.specPath) return false;
+    if (options?.featureName && node.metadata?.featureName !== options.featureName) return false;
+    return true;
+  });
+  if (filtered.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const req of filtered) {
+    const meta = req.metadata;
+    const specPath = meta?.specPath ?? "";
+    const featureName = meta?.featureName ?? "";
+    const key = `${specPath}\0${featureName}`;
+    const list = groups.get(key);
+    if (list) {
+      list.push(req);
+    } else {
+      groups.set(key, [req]);
+    }
+  }
+  const results = [];
+  for (const [, reqs] of groups) {
+    const firstReq = reqs[0];
+    const firstMeta = firstReq.metadata;
+    const specPath = firstMeta?.specPath ?? "";
+    const featureName = firstMeta?.featureName ?? "";
+    const requirements = [];
+    for (const req of reqs) {
+      const requiresEdges = store.getEdges({ from: req.id, type: "requires" });
+      const codeFiles = requiresEdges.map((edge) => {
+        const targetNode = store.getNode(edge.to);
+        return {
+          path: targetNode?.path ?? edge.to,
+          confidence: edge.confidence ?? edge.metadata?.confidence ?? 0,
+          method: edge.metadata?.method ?? "convention"
+        };
+      });
+      const verifiedByEdges = store.getEdges({ from: req.id, type: "verified_by" });
+      const testFiles = verifiedByEdges.map((edge) => {
+        const targetNode = store.getNode(edge.to);
+        return {
+          path: targetNode?.path ?? edge.to,
+          confidence: edge.confidence ?? edge.metadata?.confidence ?? 0,
+          method: edge.metadata?.method ?? "convention"
+        };
+      });
+      const hasCode = codeFiles.length > 0;
+      const hasTests = testFiles.length > 0;
+      const status = hasCode && hasTests ? "full" : hasCode ? "code-only" : hasTests ? "test-only" : "none";
+      const allConfidences = [
+        ...codeFiles.map((f) => f.confidence),
+        ...testFiles.map((f) => f.confidence)
+      ];
+      const maxConfidence = allConfidences.length > 0 ? Math.max(...allConfidences) : 0;
+      requirements.push({
+        requirementId: req.id,
+        requirementName: req.name,
+        index: req.metadata?.index ?? 0,
+        codeFiles,
+        testFiles,
+        status,
+        maxConfidence
+      });
+    }
+    requirements.sort((a, b) => a.index - b.index);
+    const total = requirements.length;
+    const withCode = requirements.filter((r) => r.codeFiles.length > 0).length;
+    const withTests = requirements.filter((r) => r.testFiles.length > 0).length;
+    const fullyTraced = requirements.filter((r) => r.status === "full").length;
+    const untraceable = requirements.filter((r) => r.status === "none").length;
+    const coveragePercent = total > 0 ? Math.round(fullyTraced / total * 100) : 0;
+    results.push({
+      specPath,
+      featureName,
+      requirements,
+      summary: { total, withCode, withTests, fullyTraced, untraceable, coveragePercent }
+    });
+  }
+  return results;
+}
+
 // src/constraints/GraphConstraintAdapter.ts
 var import_minimatch = require("minimatch");
 var import_node_path2 = require("path");
@@ -3583,6 +3971,7 @@ var GraphConstraintAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   computeDependencyGraph() {
     const fileNodes = this.store.findNodes({ type: "file" });
     const nodes = fileNodes.map((n) => n.path ?? n.id);
@@ -3634,14 +4023,14 @@ var GraphConstraintAdapter = class {
 };
 
 // src/ingest/DesignIngestor.ts
-var fs4 = __toESM(require("fs/promises"));
-var path5 = __toESM(require("path"));
+var fs5 = __toESM(require("fs/promises"));
+var path6 = __toESM(require("path"));
 function isDTCGToken(obj) {
   return typeof obj === "object" && obj !== null && "$value" in obj && "$type" in obj;
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs4.readFile(filePath, "utf-8");
+    return await fs5.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -3727,6 +4116,7 @@ var DesignIngestor = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   async ingestTokens(tokensPath) {
     const start = Date.now();
     const content = await readFileOrNull(tokensPath);
@@ -3786,8 +4176,8 @@ var DesignIngestor = class {
   async ingestAll(designDir) {
     const start = Date.now();
     const [tokensResult, intentResult] = await Promise.all([
-      this.ingestTokens(path5.join(designDir, "tokens.json")),
-      this.ingestDesignIntent(path5.join(designDir, "DESIGN.md"))
+      this.ingestTokens(path6.join(designDir, "tokens.json")),
+      this.ingestDesignIntent(path6.join(designDir, "DESIGN.md"))
     ]);
     const merged = mergeResults(tokensResult, intentResult);
     return { ...merged, durationMs: Date.now() - start };
@@ -3799,6 +4189,7 @@ var DesignConstraintAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   checkForHardcodedColors(source, file, strictness) {
     const severity = this.mapSeverity(strictness);
     const tokenNodes = this.store.findNodes({ type: "design_token" });
@@ -3882,6 +4273,7 @@ var GraphFeedbackAdapter = class {
   constructor(store) {
     this.store = store;
   }
+  store;
   computeImpactData(changedFiles) {
     const affectedTests = [];
     const affectedDocs = [];
@@ -4034,10 +4426,10 @@ var TaskIndependenceAnalyzer = class {
         includeTypes: ["file"]
       });
       for (const n of queryResult.nodes) {
-        const path6 = n.path ?? n.id.replace(/^file:/, "");
-        if (!fileSet.has(path6)) {
-          if (!result.has(path6)) {
-            result.set(path6, file);
+        const path7 = n.path ?? n.id.replace(/^file:/, "");
+        if (!fileSet.has(path7)) {
+          if (!result.has(path7)) {
+            result.set(path7, file);
           }
         }
       }
@@ -4422,6 +4814,7 @@ var VERSION = "0.2.0";
   KnowledgeIngestor,
   NODE_TYPES,
   OBSERVABILITY_TYPES,
+  RequirementIngestor,
   ResponseFormatter,
   SlackConnector,
   SyncManager,
@@ -4434,5 +4827,6 @@ var VERSION = "0.2.0";
   linkToCode,
   loadGraph,
   project,
+  queryTraceability,
   saveGraph
 });