@ncoderz/awa 1.2.0 → 1.4.0

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   rmDir,
   walkDirectory,
   writeTextFile
-} from "./chunk-3SSUJFKN.js";
+} from "./chunk-ALEGCDAZ.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -24,7 +24,7 @@ import { Command } from "commander";
 // src/_generated/package_info.ts
 var PACKAGE_INFO = {
   "name": "@ncoderz/awa",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "author": "Richard Sewell <richard.sewell@ncoderz.com>",
   "license": "MIT",
   "description": "awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage agent workflow files using templates."
@@ -89,6 +89,38 @@ function checkCodeAgainstSpec(markers, specs, config) {
       });
     }
   }
+  const implementedComponents = new Set(
+    markers.markers.filter((m) => m.type === "component").map((m) => m.id)
+  );
+  for (const componentName of specs.componentNames) {
+    if (!implementedComponents.has(componentName)) {
+      const loc = specs.idLocations.get(componentName);
+      const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.componentNames.includes(componentName));
+      findings.push({
+        severity: "warning",
+        code: "uncovered-component",
+        message: `Component '${componentName}' has no @awa-component reference`,
+        filePath: loc?.filePath ?? specFile?.filePath,
+        line: loc?.line,
+        id: componentName
+      });
+    }
+  }
+  const implementedIds = new Set(markers.markers.filter((m) => m.type === "impl").map((m) => m.id));
+  for (const acId of specs.acIds) {
+    if (!implementedIds.has(acId)) {
+      const loc = specs.idLocations.get(acId);
+      const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.acIds.includes(acId));
+      findings.push({
+        severity: "warning",
+        code: "unimplemented-ac",
+        message: `Acceptance criterion '${acId}' has no @awa-impl reference`,
+        filePath: loc?.filePath ?? specFile?.filePath,
+        line: loc?.line,
+        id: acId
+      });
+    }
+  }
   return { findings };
 }
 
@@ -122,7 +154,7 @@ var MARKER_TYPE_MAP = {
   "@awa-test": "test",
   "@awa-component": "component"
 };
-var IGNORE_FILE_RE = /@awa-ignore-file\b/;
+var IGNORE_FILE_RE = new RegExp("@awa-ignore-file\\b");
 var IGNORE_NEXT_LINE_RE = /@awa-ignore-next-line\b/;
 var IGNORE_LINE_RE = /@awa-ignore\b/;
 var IGNORE_START_RE = /@awa-ignore-start\b/;
@@ -1049,7 +1081,7 @@ async function parseSpecFile(filePath, crossRefPatterns) {
   const crossRefs = [];
   const idLocations = /* @__PURE__ */ new Map();
   const reqIdRegex = /^###\s+([A-Z][A-Z0-9]*-\d+(?:\.\d+)?)\s*:/;
-  const acIdRegex = /^-\s+\[[ x]\]\s+([A-Z][A-Z0-9]*-\d+(?:\.\d+)?_AC-\d+)\s/;
+  const acIdRegex = /^-\s+(?:\[[ x]\]\s+)?([A-Z][A-Z0-9]*-\d+(?:\.\d+)?_AC-\d+)\s/;
   const propIdRegex = /^-\s+([A-Z][A-Z0-9]*_P-\d+)\s/;
   const componentRegex = /^###\s+([A-Z][A-Z0-9]*-[A-Za-z][A-Za-z0-9]*(?:[A-Z][a-z0-9]*)*)\s*$/;
   for (const [i, line] of lines.entries()) {
@@ -2281,7 +2313,7 @@ async function prepareDiff(options) {
     throw new DiffError(`Target directory does not exist: ${options.output}`);
   }
   const targetPath = options.output;
-  const template = await templateResolver.resolve(options.template, options.refresh);
+  const template2 = await templateResolver.resolve(options.template, options.refresh);
   const features = featureResolver.resolve({
     baseFeatures: [...options.features],
     presetNames: [...options.preset],
@@ -2289,10 +2321,10 @@ async function prepareDiff(options) {
     presetDefinitions: options.presets
   });
   let mergedDir = null;
-  let templatePath = template.localPath;
+  let templatePath = template2.localPath;
   if (options.overlay.length > 0) {
     const overlayDirs = await resolveOverlays([...options.overlay], options.refresh);
-    mergedDir = await buildMergedDir(template.localPath, overlayDirs);
+    mergedDir = await buildMergedDir(template2.localPath, overlayDirs);
     templatePath = mergedDir;
   }
   return {
@@ -2302,7 +2334,7 @@ async function prepareDiff(options) {
       features,
       listUnknown: options.listUnknown
     },
-    template,
+    template: template2,
     mergedDir
   };
 }
@@ -2330,8 +2362,8 @@ async function diffCommand(cliOptions) {
     if (!silent) {
       intro("awa CLI - Template Diff");
     }
-    const { diffOptions, template, mergedDir } = await prepareDiff(options);
-    if (cliOptions.watch && template.type !== "local" && template.type !== "bundled") {
+    const { diffOptions, template: template2, mergedDir } = await prepareDiff(options);
+    if (cliOptions.watch && template2.type !== "local" && template2.type !== "bundled") {
       throw new DiffError("--watch is only supported with local template sources");
     }
     const result = await runDiff(diffOptions, options, mergedDir);
@@ -2341,11 +2373,11 @@ async function diffCommand(cliOptions) {
       }
       return result;
     }
-    logger.info(`Watching for changes in ${template.localPath}...`);
+    logger.info(`Watching for changes in ${template2.localPath}...`);
     return new Promise((resolve2) => {
       let running = false;
       const watcher = new FileWatcher({
-        directory: template.localPath,
+        directory: template2.localPath,
         onChange: async () => {
           if (running) return;
           running = true;
@@ -2507,8 +2539,8 @@ async function featuresCommand(cliOptions) {
     const fileConfig = await configLoader.load(cliOptions.config ?? null);
     const templateSource = cliOptions.template ?? fileConfig?.template ?? null;
     const refresh = cliOptions.refresh ?? fileConfig?.refresh ?? false;
-    const template = await templateResolver.resolve(templateSource, refresh);
-    const scanResult = await featureScanner.scan(template.localPath);
+    const template2 = await templateResolver.resolve(templateSource, refresh);
+    const scanResult = await featureScanner.scan(template2.localPath);
     const presets = fileConfig?.presets;
     featuresReporter.report({
       scanResult,
@@ -2548,7 +2580,7 @@ var TOOL_FEATURES = [
 var TOOL_FEATURE_VALUES = new Set(TOOL_FEATURES.map((t) => t.value));
 async function runGenerate(options, batchMode) {
   const silent = options.json || options.summary;
-  const template = await templateResolver.resolve(options.template, options.refresh);
+  const template2 = await templateResolver.resolve(options.template, options.refresh);
   const features = featureResolver.resolve({
     baseFeatures: [...options.features],
     presetNames: [...options.preset],
@@ -2580,10 +2612,10 @@ async function runGenerate(options, batchMode) {
     }
   }
   let mergedDir = null;
-  let templatePath = template.localPath;
+  let templatePath = template2.localPath;
   if (options.overlay.length > 0) {
     const overlayDirs = await resolveOverlays([...options.overlay], options.refresh);
-    mergedDir = await buildMergedDir(template.localPath, overlayDirs);
+    mergedDir = await buildMergedDir(template2.localPath, overlayDirs);
     templatePath = mergedDir;
   }
   try {
@@ -2877,8 +2909,8 @@ async function testCommand(options) {
     intro4("awa CLI - Template Test");
     const fileConfig = await configLoader.load(options.config ?? null);
     const templateSource = options.template ?? fileConfig?.template ?? null;
-    const template = await templateResolver.resolve(templateSource, false);
-    const fixtures = await discoverFixtures(template.localPath);
+    const template2 = await templateResolver.resolve(templateSource, false);
+    const fixtures = await discoverFixtures(template2.localPath);
     if (fixtures.length === 0) {
       logger.warn("No test fixtures found in _tests/ directory");
       outro4("No tests to run.");
@@ -2888,7 +2920,7 @@ async function testCommand(options) {
     const presetDefinitions = fileConfig?.presets ?? {};
     const result = await runAll(
       fixtures,
-      template.localPath,
+      template2.localPath,
       { updateSnapshots: options.updateSnapshots },
       presetDefinitions
     );
@@ -2909,6 +2941,1073 @@ async function testCommand(options) {
   }
 }
 
+// src/core/trace/content-assembler.ts
+import { readFile as readFile6 } from "fs/promises";
+var DEFAULT_BEFORE_CONTEXT = 5;
+var DEFAULT_AFTER_CONTEXT = 20;
+async function assembleContent(result, taskPath, contextOptions) {
+  const beforeCtx = contextOptions?.beforeContext ?? DEFAULT_BEFORE_CONTEXT;
+  const afterCtx = contextOptions?.afterContext ?? DEFAULT_AFTER_CONTEXT;
+  const sections = [];
+  const seen = /* @__PURE__ */ new Set();
+  if (taskPath) {
+    const content = await safeReadFile(taskPath);
+    if (content) {
+      const lineCount = content.split("\n").length;
+      sections.push({
+        type: "task",
+        filePath: taskPath,
+        startLine: 1,
+        endLine: lineCount,
+        content,
+        priority: 1
+      });
+    }
+  }
+  for (const chain of result.chains) {
+    if (chain.requirement) {
+      const key = `req:${chain.requirement.location.filePath}:${chain.requirement.id}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        const section = await extractSpecSection(
+          chain.requirement.location.filePath,
+          chain.requirement.id,
+          chain.requirement.location.line,
+          "requirement",
+          2
+        );
+        if (section) sections.push(section);
+      }
+    }
+    for (const ac of chain.acs) {
+      const key = `ac:${ac.location.filePath}:${ac.id}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        if (!chain.requirement || ac.location.filePath !== chain.requirement.location.filePath) {
+          const section = await extractSpecSection(
+            ac.location.filePath,
+            ac.id,
+            ac.location.line,
+            "requirement",
+            2
+          );
+          if (section) sections.push(section);
+        }
+      }
+    }
+    for (const comp of chain.designComponents) {
+      const key = `design:${comp.location.filePath}:${comp.id}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        const section = await extractSpecSection(
+          comp.location.filePath,
+          comp.id,
+          comp.location.line,
+          "design",
+          3
+        );
+        if (section) sections.push(section);
+      }
+    }
+    for (const impl of chain.implementations) {
+      const key = `impl:${impl.location.filePath}:${impl.location.line}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        const section = await extractCodeSection(
+          impl.location.filePath,
+          impl.location.line,
+          "implementation",
+          5,
+          beforeCtx,
+          afterCtx
+        );
+        if (section) sections.push(section);
+      }
+    }
+    for (const t of chain.tests) {
+      const key = `test:${t.location.filePath}:${t.location.line}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        const section = await extractCodeSection(
+          t.location.filePath,
+          t.location.line,
+          "test",
+          6,
+          beforeCtx,
+          afterCtx
+        );
+        if (section) sections.push(section);
+      }
+    }
+    for (const prop of chain.properties) {
+      const key = `prop:${prop.location.filePath}:${prop.id}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        const section = await extractSpecSection(
+          prop.location.filePath,
+          prop.id,
+          prop.location.line,
+          "design",
+          3
+        );
+        if (section) sections.push(section);
+      }
+    }
+  }
+  sections.sort((a, b) => a.priority - b.priority);
+  return sections;
+}
+async function extractSpecSection(filePath, _id, line, type, priority) {
+  const content = await safeReadFile(filePath);
+  if (!content) return null;
+  const lines = content.split("\n");
+  let startIdx = line - 1;
+  while (startIdx >= 0 && !/^###\s/.test(lines[startIdx] ?? "")) {
+    startIdx--;
+  }
+  if (startIdx < 0) startIdx = Math.max(0, line - 1);
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length) {
+    const l = lines[endIdx] ?? "";
+    if (/^#{2,3}\s/.test(l) && endIdx > startIdx) break;
+    endIdx++;
+  }
+  const sectionContent = lines.slice(startIdx, endIdx).join("\n").trimEnd();
+  return {
+    type,
+    filePath,
+    startLine: startIdx + 1,
+    endLine: endIdx,
+    content: sectionContent,
+    priority
+  };
+}
+async function extractCodeSection(filePath, line, type, priority, beforeContext = DEFAULT_BEFORE_CONTEXT, afterContext = DEFAULT_AFTER_CONTEXT) {
+  const content = await safeReadFile(filePath);
+  if (!content) return null;
+  const lines = content.split("\n");
+  const lineIdx = line - 1;
+  const range = findEnclosingBlock(lines, lineIdx, beforeContext, afterContext);
+  const sectionContent = lines.slice(range.start, range.end + 1).join("\n").trimEnd();
+  return {
+    type,
+    filePath,
+    startLine: range.start + 1,
+    endLine: range.end + 1,
+    content: sectionContent,
+    priority
+  };
+}
+function findEnclosingBlock(lines, lineIdx, beforeContext = DEFAULT_BEFORE_CONTEXT, afterContext = DEFAULT_AFTER_CONTEXT) {
+  let start = lineIdx;
+  for (let i = lineIdx; i >= 0; i--) {
+    const l = lines[i] ?? "";
+    if (/^\s*(export\s+)?(async\s+)?function\s/.test(l) || /^\s*(export\s+)?(const|let|var)\s+\w+\s*=\s*(async\s+)?\(/.test(l) || /^\s*(describe|test|it)\s*\(/.test(l) || /^\s*(export\s+)?class\s/.test(l) || /^\s*(export\s+)?(const|let|var)\s+\w+\s*=\s*(async\s+)?function/.test(l)) {
+      start = i;
+      break;
+    }
+    if (lineIdx - i > 50) {
+      start = Math.max(0, lineIdx - beforeContext);
+      break;
+    }
+  }
+  let braceCount = 0;
+  let foundOpen = false;
+  let end = lineIdx;
+  for (let i = start; i < lines.length; i++) {
+    const l = lines[i] ?? "";
+    for (const ch of l) {
+      if (ch === "{") {
+        braceCount++;
+        foundOpen = true;
+      } else if (ch === "}") {
+        braceCount--;
+      }
+    }
+    if (foundOpen && braceCount <= 0) {
+      end = i;
+      break;
+    }
+    if (i - start > 100) {
+      end = Math.min(lines.length - 1, lineIdx + afterContext);
+      break;
+    }
+  }
+  if (!foundOpen) {
+    start = Math.max(0, lineIdx - beforeContext);
+    end = Math.min(lines.length - 1, lineIdx + afterContext);
+  }
+  return { start, end };
+}
+async function safeReadFile(filePath) {
+  try {
+    return await readFile6(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+// src/core/trace/content-formatter.ts
+function langId(filePath) {
+  if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) return "typescript";
+  if (filePath.endsWith(".js") || filePath.endsWith(".jsx")) return "javascript";
+  if (filePath.endsWith(".md")) return "markdown";
+  if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) return "yaml";
+  if (filePath.endsWith(".json")) return "json";
+  if (filePath.endsWith(".tsp")) return "typespec";
+  return "";
+}
+function sectionHeading(type) {
+  switch (type) {
+    case "task":
+      return "Task";
+    case "requirement":
+      return "Requirement";
+    case "design":
+      return "Design";
+    case "implementation":
+      return "Implementation";
+    case "test":
+      return "Test";
+    default:
+      return "Other";
+  }
+}
+function formatContentMarkdown(sections, queryLabel, footer) {
+  const lines = [];
+  lines.push(`# Context: ${queryLabel}`);
+  lines.push("");
+  let lastType = null;
+  for (const section of sections) {
+    if (section.type !== lastType) {
+      lines.push(`## ${sectionHeading(section.type)}`);
+      lines.push("");
+      lastType = section.type;
+    }
+    lines.push(`> From: ${section.filePath} (lines ${section.startLine}-${section.endLine})`);
+    lines.push("");
+    const isCode = section.type === "implementation" || section.type === "test";
+    if (isCode) {
+      const lang = langId(section.filePath);
+      lines.push(`\`\`\`${lang}`);
+      lines.push(section.content);
+      lines.push("```");
+    } else {
+      lines.push(section.content);
+    }
+    lines.push("");
+  }
+  if (footer) {
+    lines.push(`---`);
+    lines.push(footer);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function formatContentJson(sections, queryLabel, footer) {
+  const result = {
+    query: queryLabel,
+    sections: sections.map((s) => ({
+      type: s.type,
+      filePath: s.filePath,
+      startLine: s.startLine,
+      endLine: s.endLine,
+      content: s.content,
+      priority: s.priority
+    })),
+    estimatedTokens: Math.ceil(sections.reduce((sum, s) => sum + s.content.length, 0) / 4),
+    filesIncluded: new Set(sections.map((s) => s.filePath)).size,
+    ...footer ? { truncated: true, truncationMessage: footer } : {}
+  };
+  return JSON.stringify(result, null, 2);
+}
+
+// src/core/trace/formatter.ts
+function formatTree(result) {
+  const lines = [];
+  for (const chain of result.chains) {
+    lines.push(...formatChainTree(chain));
+    lines.push("");
+  }
+  for (const id of result.notFound) {
+    lines.push(`\u2717 ${id}: not found`);
+  }
+  return lines.join("\n").trimEnd();
+}
+function formatChainTree(chain) {
+  const lines = [];
+  const queryId = chain.queryId;
+  lines.push(`${queryId}`);
+  if (chain.requirement) {
+    lines.push("");
+    lines.push("  \u25B2 Requirement");
+    const r = chain.requirement;
+    lines.push(`  \u2502  ${r.id} (${r.location.filePath}:${r.location.line})`);
+  }
+  if (chain.acs.length > 0) {
+    lines.push("");
+    lines.push("  \u25BC Acceptance Criteria");
+    for (const ac of chain.acs) {
+      lines.push(`  \u2502  ${ac.id} (${ac.location.filePath}:${ac.location.line})`);
+    }
+  }
+  if (chain.designComponents.length > 0) {
+    lines.push("");
+    lines.push("  \u25BC Design");
+    for (const comp of chain.designComponents) {
+      lines.push(`  \u2502  ${comp.id} (${comp.location.filePath}:${comp.location.line})`);
+    }
+  }
+  if (chain.properties.length > 0) {
+    lines.push("");
+    lines.push("  \u25BC Properties");
+    for (const prop of chain.properties) {
+      lines.push(`  \u2502  ${prop.id} (${prop.location.filePath}:${prop.location.line})`);
+    }
+  }
+  if (chain.implementations.length > 0) {
+    lines.push("");
+    lines.push("  \u25BC Implementation");
+    for (const impl of chain.implementations) {
+      lines.push(
+        `  \u2502  ${impl.location.filePath}:${impl.location.line}  (@awa-${impl.type === "implementation" ? "impl" : "component"}: ${impl.id})`
+      );
+    }
+  }
+  if (chain.tests.length > 0) {
+    lines.push("");
+    lines.push("  \u25BC Tests");
+    for (const t of chain.tests) {
+      lines.push(`  \u2502  ${t.location.filePath}:${t.location.line}  (@awa-test: ${t.id})`);
+    }
+  }
+  return lines;
+}
+function formatList(result) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const chain of result.chains) {
+    if (chain.requirement) {
+      paths.add(`${chain.requirement.location.filePath}:${chain.requirement.location.line}`);
+    }
+    for (const ac of chain.acs) {
+      paths.add(`${ac.location.filePath}:${ac.location.line}`);
+    }
+    for (const comp of chain.designComponents) {
+      paths.add(`${comp.location.filePath}:${comp.location.line}`);
+    }
+    for (const prop of chain.properties) {
+      paths.add(`${prop.location.filePath}:${prop.location.line}`);
+    }
+    for (const impl of chain.implementations) {
+      paths.add(`${impl.location.filePath}:${impl.location.line}`);
+    }
+    for (const t of chain.tests) {
+      paths.add(`${t.location.filePath}:${t.location.line}`);
+    }
+  }
+  return [...paths].join("\n");
+}
+function formatJson(result) {
+  const output = {
+    chains: result.chains.map((chain) => ({
+      queryId: chain.queryId,
+      requirement: chain.requirement ? {
+        id: chain.requirement.id,
+        filePath: chain.requirement.location.filePath,
+        line: chain.requirement.location.line
+      } : null,
+      acs: chain.acs.map((ac) => ({
+        id: ac.id,
+        filePath: ac.location.filePath,
+        line: ac.location.line
+      })),
+      designComponents: chain.designComponents.map((c) => ({
+        id: c.id,
+        filePath: c.location.filePath,
+        line: c.location.line
+      })),
+      implementations: chain.implementations.map((i) => ({
+        id: i.id,
+        filePath: i.location.filePath,
+        line: i.location.line
+      })),
+      tests: chain.tests.map((t) => ({
+        id: t.id,
+        filePath: t.location.filePath,
+        line: t.location.line
+      })),
+      properties: chain.properties.map((p) => ({
+        id: p.id,
+        filePath: p.location.filePath,
+        line: p.location.line
+      }))
+    })),
+    notFound: result.notFound
+  };
+  return JSON.stringify(output, null, 2);
+}
+
+// src/core/trace/index-builder.ts
+function buildTraceIndex(specs, markers) {
+  const reqToACs = /* @__PURE__ */ new Map();
+  const acToDesignComponents = /* @__PURE__ */ new Map();
+  const acToCodeLocations = /* @__PURE__ */ new Map();
+  const acToTestLocations = /* @__PURE__ */ new Map();
+  const propertyToTestLocations = /* @__PURE__ */ new Map();
+  const componentToCodeLocations = /* @__PURE__ */ new Map();
+  const acToReq = /* @__PURE__ */ new Map();
+  const componentToACs = /* @__PURE__ */ new Map();
+  const propertyToACs = /* @__PURE__ */ new Map();
+  buildRequirementMaps(specs, reqToACs, acToReq);
+  buildDesignMaps(specs, acToDesignComponents, componentToACs, propertyToACs);
+  buildMarkerMaps(
+    markers.markers,
+    acToCodeLocations,
+    acToTestLocations,
+    propertyToTestLocations,
+    componentToCodeLocations
+  );
+  const allIds = /* @__PURE__ */ new Set([
+    ...specs.requirementIds,
+    ...specs.acIds,
+    ...specs.propertyIds,
+    ...specs.componentNames
+  ]);
+  const idLocations = /* @__PURE__ */ new Map();
+  for (const [id, loc] of specs.idLocations) {
+    idLocations.set(id, loc);
+  }
+  return {
+    reqToACs,
+    acToDesignComponents,
+    acToCodeLocations,
+    acToTestLocations,
+    propertyToTestLocations,
+    componentToCodeLocations,
+    acToReq,
+    componentToACs,
+    propertyToACs,
+    idLocations,
+    allIds
+  };
+}
+function buildRequirementMaps(specs, reqToACs, acToReq) {
+  for (const acId of specs.acIds) {
+    const parentReq = extractParentRequirement(acId);
+    if (parentReq && specs.requirementIds.has(parentReq)) {
+      pushToMap(reqToACs, parentReq, acId);
+      acToReq.set(acId, parentReq);
+    }
+  }
+  for (const reqId of specs.requirementIds) {
+    const dotIdx = reqId.lastIndexOf(".");
+    if (dotIdx !== -1) {
+      const parentReq = reqId.slice(0, dotIdx);
+      if (specs.requirementIds.has(parentReq)) {
+      }
+    }
+  }
+}
+function buildDesignMaps(specs, acToDesignComponents, componentToACs, propertyToACs) {
+  for (const specFile of specs.specFiles) {
+    if (specFile.componentNames.length === 0 && specFile.crossRefs.length === 0) {
+      continue;
+    }
+    const componentsByLine = specFile.componentNames.map((name) => ({
+      name,
+      line: specFile.idLocations?.get(name)?.line ?? 0
+    })).sort((a, b) => a.line - b.line);
+    for (const crossRef of specFile.crossRefs) {
+      const ownerComponent = findOwnerComponent(componentsByLine, crossRef.line);
+      if (crossRef.type === "implements" && ownerComponent) {
+        for (const acId of crossRef.ids) {
+          pushToMap(acToDesignComponents, acId, ownerComponent);
+          pushToMap(componentToACs, ownerComponent, acId);
+        }
+      }
+      if (crossRef.type === "validates") {
+        const ownerProperty = findOwnerProperty(specFile, crossRef.line);
+        if (ownerProperty) {
+          for (const acId of crossRef.ids) {
+            pushToMap(propertyToACs, ownerProperty, acId);
+          }
+        }
+      }
+    }
+  }
+}
+function buildMarkerMaps(markers, acToCodeLocations, acToTestLocations, propertyToTestLocations, componentToCodeLocations) {
+  for (const marker of markers) {
+    const loc = { filePath: marker.filePath, line: marker.line };
+    switch (marker.type) {
+      case "impl":
+        pushToMap(acToCodeLocations, marker.id, loc);
+        break;
+      case "test":
+        if (marker.id.includes("_P-")) {
+          pushToMap(propertyToTestLocations, marker.id, loc);
+        } else {
+          pushToMap(acToTestLocations, marker.id, loc);
+        }
+        break;
+      case "component":
+        pushToMap(componentToCodeLocations, marker.id, loc);
+        break;
+    }
+  }
+}
+function extractParentRequirement(acId) {
+  const idx = acId.indexOf("_AC-");
+  return idx !== -1 ? acId.slice(0, idx) : null;
+}
+function findOwnerComponent(componentsByLine, line) {
+  let owner = null;
+  for (const comp of componentsByLine) {
+    if (comp.line <= line) {
+      owner = comp.name;
+    } else {
+      break;
+    }
+  }
+  return owner;
+}
+function findOwnerProperty(specFile, validateLine) {
+  let owner = null;
+  let closestLine = 0;
+  for (const propId of specFile.propertyIds) {
+    const loc = specFile.idLocations?.get(propId);
+    if (loc && loc.line <= validateLine && loc.line > closestLine) {
+      closestLine = loc.line;
+      owner = propId;
+    }
+  }
+  return owner;
+}
+function pushToMap(map, key, value) {
+  const existing = map.get(key);
+  if (existing) {
+    existing.push(value);
+  } else {
+    map.set(key, [value]);
+  }
+}
+
+// src/core/trace/input-resolver.ts
+import { readFile as readFile7 } from "fs/promises";
+function resolveIds(ids, index) {
+  const resolved = [];
+  const warnings = [];
+  for (const id of ids) {
+    if (index.allIds.has(id)) {
+      resolved.push(id);
+    } else {
+      warnings.push(`ID '${id}' not found in any spec or code`);
+    }
+  }
+  return { ids: resolved, warnings };
+}
+async function resolveTaskFile(taskPath, index) {
+  let content;
+  try {
+    content = await readFile7(taskPath, "utf-8");
+  } catch {
+    return { ids: [], warnings: [`Task file not found: ${taskPath}`] };
+  }
+  const ids = /* @__PURE__ */ new Set();
+  const warnings = [];
+  const lines = content.split("\n");
+  const idRegex = /[A-Z][A-Z0-9]*-\d+(?:\.\d+)?(?:_AC-\d+)?|[A-Z][A-Z0-9]*_P-\d+/g;
+  for (const line of lines) {
+    if (/^\s*IMPLEMENTS:/.test(line) || /^\s*TESTS:/.test(line)) {
+      let match = idRegex.exec(line);
+      while (match !== null) {
+        ids.add(match[0]);
+        match = idRegex.exec(line);
+      }
+    }
+  }
+  const traceLineRegex = /^- ([A-Z][A-Z0-9]*(?:-\d+(?:\.\d+)?(?:_AC-\d+)?|_P-\d+))/;
+  let inTraceSection = false;
+  for (const line of lines) {
+    if (/^## Requirements Traceability/.test(line)) {
+      inTraceSection = true;
+      continue;
+    }
+    if (inTraceSection && /^## /.test(line)) {
+      inTraceSection = false;
+      continue;
+    }
+    if (inTraceSection) {
+      const traceMatch = traceLineRegex.exec(line);
+      if (traceMatch?.[1]) {
+        ids.add(traceMatch[1]);
+      }
+    }
+  }
+  const resolved = [];
+  for (const id of ids) {
+    if (index.allIds.has(id)) {
+      resolved.push(id);
+    } else {
+      warnings.push(`ID '${id}' from task file not found in specs`);
+    }
+  }
+  if (resolved.length === 0 && warnings.length === 0) {
+    warnings.push(`No traceability IDs found in task file: ${taskPath}`);
+  }
+  return { ids: resolved, warnings };
+}
+async function resolveSourceFile(filePath, index) {
+  let content;
+  try {
+    content = await readFile7(filePath, "utf-8");
+  } catch {
+    return { ids: [], warnings: [`Source file not found: ${filePath}`] };
+  }
+  const ids = /* @__PURE__ */ new Set();
+  const warnings = [];
+  const markerRegex = /@awa-(?:impl|test|component):\s*(.+)/g;
+  const idTokenRegex = /[A-Z][A-Z0-9]*(?:[-_][A-Za-z0-9]+)*(?:\.\d+)?/g;
+  const lines = content.split("\n");
+  for (const line of lines) {
+    let markerMatch = markerRegex.exec(line);
+    while (markerMatch !== null) {
+      const idsText = markerMatch[1] ?? "";
+      let idMatch = idTokenRegex.exec(idsText);
+      while (idMatch !== null) {
+        ids.add(idMatch[0]);
+        idMatch = idTokenRegex.exec(idsText);
+      }
+      markerMatch = markerRegex.exec(line);
+    }
+  }
+  const resolved = [];
+  for (const id of ids) {
+    if (index.allIds.has(id)) {
+      resolved.push(id);
+    } else {
+      warnings.push(`Marker ID '${id}' not found in specs`);
+    }
+  }
+  if (resolved.length === 0 && warnings.length === 0) {
+    warnings.push(`No traceability markers found in file: ${filePath}`);
+  }
+  return { ids: resolved, warnings };
+}
+
+// src/core/trace/resolver.ts
+function resolveTrace(index, ids, options) {
+  const chains = [];
+  const notFound = [];
+  for (const id of ids) {
+    if (!index.allIds.has(id)) {
+      notFound.push(id);
+      continue;
+    }
+    const chain = resolveChain(index, id, options);
+    if (chain) {
+      chains.push(chain);
+    }
+  }
+  return { chains, notFound };
+}
+function resolveChain(index, id, options) {
+  const idType = detectIdType(id);
+  const scope = options.scope;
+  let requirement;
+  let acs = [];
+  let designComponents = [];
+  let implementations = [];
+  let tests = [];
+  let properties = [];
+  switch (idType) {
+    case "requirement":
+      resolveFromRequirement(index, id, options, {
+        requirement: (n) => {
+          requirement = n;
+        },
+        acs,
+        designComponents,
+        implementations,
+        tests,
+        properties
+      });
+      break;
+    case "ac":
+      resolveFromAC(index, id, options, {
+        requirement: (n) => {
+          requirement = n;
+        },
+        acs,
+        designComponents,
+        implementations,
+        tests,
+        properties
+      });
+      break;
+    case "property":
+      resolveFromProperty(index, id, options, {
+        requirement: (n) => {
+          requirement = n;
+        },
+        acs,
+        designComponents,
+        implementations,
+        tests,
+        properties
+      });
+      break;
+    case "component":
+      resolveFromComponent(index, id, options, {
+        requirement: (n) => {
+          requirement = n;
+        },
+        acs,
+        designComponents,
+        implementations,
+        tests,
+        properties
+      });
+      break;
+  }
+  if (scope) {
+    acs = acs.filter((n) => n.id.startsWith(scope));
+    designComponents = designComponents.filter((n) => n.id.startsWith(scope));
+    implementations = implementations.filter((n) => matchesScope(n, scope, index));
+    tests = tests.filter((n) => matchesScope(n, scope, index));
+    properties = properties.filter((n) => n.id.startsWith(scope));
+    if (requirement && !requirement.id.startsWith(scope)) {
+      requirement = void 0;
+    }
+  }
+  if (options.noCode) {
+    implementations = [];
+  }
+  if (options.noTests) {
+    tests = [];
+    properties = [];
+  }
+  return {
+    queryId: id,
+    requirement,
+    acs: deduplicateNodes(acs),
+    designComponents: deduplicateNodes(designComponents),
+    implementations: deduplicateNodes(implementations),
+    tests: deduplicateNodes(tests),
+    properties: deduplicateNodes(properties)
+  };
+}
+function resolveFromRequirement(index, reqId, options, collectors) {
+  const loc = index.idLocations.get(reqId);
+  if (loc) {
+    collectors.requirement({ id: reqId, type: "requirement", location: loc });
+  }
+  if (options.direction === "reverse") return;
+  const acIds = index.reqToACs.get(reqId) ?? [];
+  for (const acId of acIds) {
+    const acLoc = index.idLocations.get(acId);
+    if (acLoc) {
+      collectors.acs.push({ id: acId, type: "ac", location: acLoc });
+    }
+    if (withinDepth(options.depth, 1)) {
+      resolveACDownstream(index, acId, options, collectors, 1);
+    }
+  }
+}
+function resolveFromAC(index, acId, options, collectors) {
+  const acLoc = index.idLocations.get(acId);
+  if (acLoc) {
+    collectors.acs.push({ id: acId, type: "ac", location: acLoc });
+  }
+  if (options.direction !== "forward") {
+    const reqId = index.acToReq.get(acId);
+    if (reqId) {
+      const reqLoc = index.idLocations.get(reqId);
+      if (reqLoc) {
+        collectors.requirement({ id: reqId, type: "requirement", location: reqLoc });
+      }
+    }
+  }
+  if (options.direction !== "reverse") {
+    resolveACDownstream(index, acId, options, collectors, 0);
+  }
+}
+function resolveFromProperty(index, propId, options, collectors) {
+  const propLoc = index.idLocations.get(propId);
+  if (propLoc) {
+    collectors.properties.push({ id: propId, type: "property", location: propLoc });
+  }
+  if (options.direction !== "reverse") {
+    const testLocs = index.propertyToTestLocations.get(propId) ?? [];
+    for (const loc of testLocs) {
+      collectors.tests.push({ id: propId, type: "test", location: loc });
+    }
+  }
+  if (options.direction !== "forward") {
+    const acIds = index.propertyToACs.get(propId) ?? [];
+    for (const acId of acIds) {
+      const acLoc = index.idLocations.get(acId);
+      if (acLoc) {
+        collectors.acs.push({ id: acId, type: "ac", location: acLoc });
+      }
+      if (withinDepth(options.depth, 1)) {
+        const reqId = index.acToReq.get(acId);
+        if (reqId) {
+          const reqLoc = index.idLocations.get(reqId);
+          if (reqLoc) {
+            collectors.requirement({ id: reqId, type: "requirement", location: reqLoc });
+          }
+        }
+      }
+    }
+  }
+}
+function resolveFromComponent(index, componentId, options, collectors) {
+  const compLoc = index.idLocations.get(componentId);
+  if (compLoc) {
+    collectors.designComponents.push({ id: componentId, type: "component", location: compLoc });
+  }
+  if (options.direction !== "reverse") {
+    const codeLocs = index.componentToCodeLocations.get(componentId) ?? [];
+    for (const loc of codeLocs) {
+      collectors.implementations.push({
+        id: componentId,
+        type: "implementation",
+        location: loc
+      });
+    }
+  }
+  if (options.direction !== "forward") {
+    const acIds = index.componentToACs.get(componentId) ?? [];
+    for (const acId of acIds) {
+      const acLoc = index.idLocations.get(acId);
+      if (acLoc) {
+        collectors.acs.push({ id: acId, type: "ac", location: acLoc });
+      }
+      if (withinDepth(options.depth, 1)) {
+        const reqId = index.acToReq.get(acId);
+        if (reqId) {
+          const reqLoc = index.idLocations.get(reqId);
+          if (reqLoc) {
+            collectors.requirement({ id: reqId, type: "requirement", location: reqLoc });
+          }
+        }
+      }
+    }
+  }
+}
+function resolveACDownstream(index, acId, options, collectors, currentDepth) {
+  const components = index.acToDesignComponents.get(acId) ?? [];
+  for (const comp of components) {
+    const compLoc = index.idLocations.get(comp);
+    if (compLoc) {
+      collectors.designComponents.push({ id: comp, type: "component", location: compLoc });
+    }
+  }
+  if (!withinDepth(options.depth, currentDepth + 1)) return;
+  const codeLocs = index.acToCodeLocations.get(acId) ?? [];
+  for (const loc of codeLocs) {
+    collectors.implementations.push({ id: acId, type: "implementation", location: loc });
+  }
+  const testLocs = index.acToTestLocations.get(acId) ?? [];
+  for (const loc of testLocs) {
+    collectors.tests.push({ id: acId, type: "test", location: loc });
+  }
+}
+function detectIdType(id) {
+  if (id.includes("_AC-")) return "ac";
+  if (id.includes("_P-")) return "property";
+  if (/^[A-Z][A-Z0-9]*-\d+/.test(id)) return "requirement";
+  return "component";
+}
+function withinDepth(maxDepth, current) {
+  if (maxDepth === void 0) return true;
+  return current < maxDepth;
+}
+function matchesScope(node, scope, _index) {
+  return node.id.startsWith(scope);
+}
+function deduplicateNodes(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const node of nodes) {
+    const key = `${node.id}:${node.location.filePath}:${node.location.line}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(node);
+    }
+  }
+  return result;
+}
+
+// src/core/trace/scanner.ts
+function buildScanConfig(fileConfig, overrides) {
+  const section = fileConfig?.check;
+  return {
+    specGlobs: toStringArray3(section?.["spec-globs"]) ?? [...DEFAULT_CHECK_CONFIG.specGlobs],
+    codeGlobs: toStringArray3(section?.["code-globs"]) ?? [...DEFAULT_CHECK_CONFIG.codeGlobs],
+    specIgnore: toStringArray3(section?.["spec-ignore"]) ?? [...DEFAULT_CHECK_CONFIG.specIgnore],
+    codeIgnore: toStringArray3(section?.["code-ignore"]) ?? [...DEFAULT_CHECK_CONFIG.codeIgnore],
+    ignoreMarkers: toStringArray3(section?.["ignore-markers"]) ?? [
+      ...DEFAULT_CHECK_CONFIG.ignoreMarkers
+    ],
+    markers: toStringArray3(section?.markers) ?? [...DEFAULT_CHECK_CONFIG.markers],
+    idPattern: typeof section?.["id-pattern"] === "string" ? section["id-pattern"] : DEFAULT_CHECK_CONFIG.idPattern,
+    crossRefPatterns: toStringArray3(section?.["cross-ref-patterns"]) ?? [
+      ...DEFAULT_CHECK_CONFIG.crossRefPatterns
+    ],
+    format: DEFAULT_CHECK_CONFIG.format,
+    schemaDir: DEFAULT_CHECK_CONFIG.schemaDir,
+    schemaEnabled: false,
+    allowWarnings: true,
+    specOnly: false,
+    ...overrides
+  };
+}
+async function scan(configPath) {
+  const fileConfig = await configLoader.load(configPath ?? null);
+  const config = buildScanConfig(fileConfig);
+  const [markers, specs] = await Promise.all([scanMarkers(config), parseSpecs(config)]);
+  return { markers, specs, config };
+}
+function toStringArray3(value) {
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value;
+  }
+  return null;
+}
+
+// src/core/trace/token-estimator.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function applyTokenBudget(sections, maxTokens) {
+  if (maxTokens <= 0) {
+    return { sections: [], truncated: sections.length > 0, footer: null };
+  }
+  const result = [];
+  let usedTokens = 0;
+  let omittedCount = 0;
+  for (const section of sections) {
+    const sectionTokens = estimateTokens(section.content);
+    if (usedTokens + sectionTokens <= maxTokens) {
+      result.push(section);
+      usedTokens += sectionTokens;
+    } else if (result.length === 0) {
+      const availableChars = maxTokens * 4;
+      const truncatedContent = section.content.slice(0, availableChars);
+      result.push({ ...section, content: truncatedContent });
+      usedTokens = maxTokens;
+      omittedCount = sections.length - 1;
+      break;
+    } else {
+      omittedCount++;
+    }
+  }
+  if (omittedCount === 0) {
+    omittedCount = sections.length - result.length;
+  }
+  const truncated = omittedCount > 0;
+  const footer = truncated ? `... ${omittedCount} more section${omittedCount === 1 ? "" : "s"} omitted (use --max-tokens to increase)` : null;
+  return { sections: result, truncated, footer };
+}
+
+// src/commands/trace.ts
+async function traceCommand(options) {
+  try {
+    const { markers, specs } = await scan(options.config);
+    const index = buildTraceIndex(specs, markers);
+    let ids;
+    let warnings = [];
+    if (options.all) {
+      ids = [...index.allIds];
+    } else if (options.task) {
+      const resolved = await resolveTaskFile(options.task, index);
+      ids = resolved.ids;
+      warnings = resolved.warnings;
+    } else if (options.file) {
+      const resolved = await resolveSourceFile(options.file, index);
+      ids = resolved.ids;
+      warnings = resolved.warnings;
+    } else if (options.ids.length > 0) {
+      const resolved = resolveIds([...options.ids], index);
+      ids = resolved.ids;
+      warnings = resolved.warnings;
+    } else {
+      logger.error("No IDs, --all, --task, or --file specified");
+      return 1;
+    }
+    for (const w of warnings) {
+      logger.warn(w);
+    }
+    if (ids.length === 0) {
+      if (options.file) {
+        logger.error("No traceability markers found in file");
+      } else if (options.task) {
+        logger.error("No traceability IDs found in task file");
+      } else {
+        logger.error("No valid IDs found");
+      }
+      return 1;
+    }
+    const traceOptions = {
+      direction: options.direction,
+      depth: options.depth,
+      scope: options.scope,
+      noCode: options.noCode,
+      noTests: options.noTests
+    };
+    const result = resolveTrace(index, ids, traceOptions);
+    if (result.chains.length === 0 && result.notFound.length > 0) {
+      for (const id of result.notFound) {
+        logger.error(`ID not found: ${id}`);
+      }
+      return 1;
+    }
+    let output;
+    const isContentMode = options.content || options.maxTokens !== void 0;
+    const queryLabel = ids.join(", ");
+    if (isContentMode) {
+      const sections = await assembleContent(result, options.task, {
+        beforeContext: options.beforeContext,
+        afterContext: options.afterContext
+      });
+      let finalSections = sections;
+      let footer = null;
+      if (options.maxTokens !== void 0) {
+        const budgeted = applyTokenBudget(sections, options.maxTokens);
+        finalSections = budgeted.sections;
+        footer = budgeted.footer;
+      }
+      if (options.json) {
+        output = formatContentJson(finalSections, queryLabel, footer);
+      } else {
+        output = formatContentMarkdown(finalSections, queryLabel, footer);
+      }
+    } else if (options.list) {
+      output = formatList(result);
+    } else if (options.json) {
+      output = formatJson(result);
+    } else {
+      output = formatTree(result);
+    }
+    process.stdout.write(output);
+    if (result.notFound.length > 0) {
+      for (const id of result.notFound) {
+        logger.warn(`ID not found: ${id}`);
+      }
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(error.message);
+    } else {
+      logger.error(String(error));
+    }
+    return 2;
+  }
+}
+
 // src/utils/update-check.ts
 import chalk5 from "chalk";
 function compareSemver(a, b) {
@@ -2964,7 +4063,7 @@ function printUpdateWarning(log, result) {
 }
 
 // src/utils/update-check-cache.ts
-import { mkdir as mkdir3, readFile as readFile6, writeFile } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile8, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join as join11 } from "path";
 var CACHE_DIR = join11(homedir(), ".cache", "awa");
@@ -2972,7 +4071,7 @@ var CACHE_FILE = join11(CACHE_DIR, "update-check.json");
 var DEFAULT_INTERVAL_MS = 864e5;
 async function shouldCheck(intervalMs = DEFAULT_INTERVAL_MS) {
   try {
-    const raw = await readFile6(CACHE_FILE, "utf-8");
+    const raw = await readFile8(CACHE_FILE, "utf-8");
     const data = JSON.parse(raw);
     if (typeof data.timestamp !== "number" || typeof data.latestVersion !== "string") {
       return true;
@@ -2998,34 +4097,44 @@ async function writeCache(latestVersion) {
 var version = PACKAGE_INFO.version;
 var program = new Command();
 program.name("awa").description("awa - tool for generating AI coding agent configuration files").version(version, "-v, --version", "Display version number");
-program.command("generate").alias("init").description("Generate AI agent configuration files from templates").argument("[output]", "Output directory (optional if specified in config)").option("-t, --template <source>", "Template source (local path or Git repository)").option("-f, --features <flag...>", "Feature flags (can be specified multiple times)").option("--preset <name...>", "Preset names to enable (can be specified multiple times)").option(
-  "--remove-features <flag...>",
-  "Feature flags to remove (can be specified multiple times)"
-).option("--force", "Force overwrite existing files without prompting", false).option("--dry-run", "Preview changes without modifying files", false).option(
-  "--delete",
-  "Enable deletion of files listed in the delete list (default: warn only)",
-  false
-).option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--all", "Process all named targets from config", false).option("--target <name>", "Process a specific named target from config").option("--overlay <path...>", "Overlay directory paths applied over base template (repeatable)").option("--json", "Output results as JSON (implies --dry-run)", false).option("--summary", "Output compact one-line summary", false).action(async (output, options) => {
-  const cliOptions = {
-    output,
-    template: options.template,
-    features: options.features,
-    preset: options.preset,
-    removeFeatures: options.removeFeatures,
-    force: options.force,
-    dryRun: options.dryRun,
-    delete: options.delete,
-    config: options.config,
-    refresh: options.refresh,
-    all: options.all,
-    target: options.target,
-    overlay: options.overlay || [],
-    json: options.json,
-    summary: options.summary
-  };
-  await generateCommand(cliOptions);
-});
-program.command("diff").description("Compare template output with existing target directory").argument("[target]", "Target directory to compare against (optional if specified in config)").option("-t, --template <source>", "Template source (local path or Git repository)").option("-f, --features <flag...>", "Feature flags (can be specified multiple times)").option("--preset <name...>", "Preset names to enable (can be specified multiple times)").option(
+var template = new Command("template").description(
+  "Template operations (generate, diff, features, test)"
+);
+function configureGenerateCommand(cmd) {
+  return cmd.description("Generate AI agent configuration files from templates").argument("[output]", "Output directory (optional if specified in config)").option("-t, --template <source>", "Template source (local path or Git repository)").option("-f, --features <flag...>", "Feature flags (can be specified multiple times)").option("--preset <name...>", "Preset names to enable (can be specified multiple times)").option(
+    "--remove-features <flag...>",
+    "Feature flags to remove (can be specified multiple times)"
+  ).option("--force", "Force overwrite existing files without prompting", false).option("--dry-run", "Preview changes without modifying files", false).option(
+    "--delete",
+    "Enable deletion of files listed in the delete list (default: warn only)",
+    false
+  ).option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--all", "Process all named targets from config", false).option("--target <name>", "Process a specific named target from config").option(
+    "--overlay <path...>",
+    "Overlay directory paths applied over base template (repeatable)"
+  ).option("--json", "Output results as JSON (implies --dry-run)", false).option("--summary", "Output compact one-line summary", false).action(async (output, options) => {
+    const cliOptions = {
+      output,
+      template: options.template,
+      features: options.features,
+      preset: options.preset,
+      removeFeatures: options.removeFeatures,
+      force: options.force,
+      dryRun: options.dryRun,
+      delete: options.delete,
+      config: options.config,
+      refresh: options.refresh,
+      all: options.all,
+      target: options.target,
+      overlay: options.overlay || [],
+      json: options.json,
+      summary: options.summary
+    };
+    await generateCommand(cliOptions);
+  });
+}
+configureGenerateCommand(template.command("generate"));
+configureGenerateCommand(program.command("init"));
+template.command("diff").description("Compare template output with existing target directory").argument("[target]", "Target directory to compare against (optional if specified in config)").option("-t, --template <source>", "Template source (local path or Git repository)").option("-f, --features <flag...>", "Feature flags (can be specified multiple times)").option("--preset <name...>", "Preset names to enable (can be specified multiple times)").option(
   "--remove-features <flag...>",
   "Feature flags to remove (can be specified multiple times)"
 ).option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--list-unknown", "Include target-only files in diff results", false).option("--all", "Process all named targets from config", false).option("--target <name>", "Process a specific named target from config").option("-w, --watch", "Watch template directory for changes and re-run diff", false).option("--overlay <path...>", "Overlay directory paths applied over base template (repeatable)").option("--json", "Output results as JSON", false).option("--summary", "Output compact one-line summary", false).action(async (target, options) => {
@@ -3071,7 +4180,7 @@ program.command("check").description(
   const exitCode = await checkCommand(cliOptions);
   process.exit(exitCode);
 });
-program.command("features").description("Discover feature flags available in a template").option("-t, --template <source>", "Template source (local path or Git repository)").option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--json", "Output results as JSON", false).action(async (options) => {
+template.command("features").description("Discover feature flags available in a template").option("-t, --template <source>", "Template source (local path or Git repository)").option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--json", "Output results as JSON", false).action(async (options) => {
   const exitCode = await featuresCommand({
     template: options.template,
     config: options.config,
@@ -3080,7 +4189,7 @@ program.command("features").description("Discover feature flags available in a t
   });
   process.exit(exitCode);
 });
-program.command("test").description("Run template test fixtures to verify expected output").option("-t, --template <source>", "Template source (local path or Git repository)").option("-c, --config <path>", "Path to configuration file").option("--update-snapshots", "Update stored snapshots with current rendered output", false).action(async (options) => {
+template.command("test").description("Run template test fixtures to verify expected output").option("-t, --template <source>", "Template source (local path or Git repository)").option("-c, --config <path>", "Path to configuration file").option("--update-snapshots", "Update stored snapshots with current rendered output", false).action(async (options) => {
   const testOptions = {
     template: options.template,
     config: options.config,
@@ -3089,6 +4198,29 @@ program.command("test").description("Run template test fixtures to verify expect
   const exitCode = await testCommand(testOptions);
   process.exit(exitCode);
 });
+program.addCommand(template);
+program.command("trace").description("Explore traceability chains and assemble context from specs, code, and tests").argument("[ids...]", "Traceability ID(s) to trace").option("--all", "Trace all known IDs in the project", false).option("--task <path>", "Resolve IDs from a task file").option("--file <path>", "Resolve IDs from a source file's markers").option("--content", "Output actual file sections instead of locations", false).option("--list", "Output file paths only (no content or tree)", false).option("--max-tokens <n>", "Cap content output size (implies --content)").option("--depth <n>", "Maximum traversal depth").option("--scope <code>", "Limit results to a feature code").option("--direction <dir>", "Traversal direction: both, forward, reverse", "both").option("--no-code", "Exclude source code (spec-only context)").option("--no-tests", "Exclude test files").option("--json", "Output as JSON", false).option("-A <n>", "Lines of context after a code marker (--content only; default: 20)").option("-B <n>", "Lines of context before a code marker (--content only; default: 5)").option("-C <n>", "Lines of context before and after (--content only; overrides -A and -B)").option("-c, --config <path>", "Path to configuration file").action(async (ids, options) => {
+  const traceOptions = {
+    ids,
+    all: options.all,
+    task: options.task,
+    file: options.file,
+    content: options.content,
+    list: options.list,
+    json: options.json,
+    maxTokens: options.maxTokens !== void 0 ? Number(options.maxTokens) : void 0,
+    depth: options.depth !== void 0 ? Number(options.depth) : void 0,
+    scope: options.scope,
+    direction: options.direction,
+    noCode: options.code === false,
+    noTests: options.tests === false,
+    beforeContext: options.C !== void 0 ? Number(options.C) : options.B !== void 0 ? Number(options.B) : void 0,
+    afterContext: options.C !== void 0 ? Number(options.C) : options.A !== void 0 ? Number(options.A) : void 0,
+    config: options.config
+  };
+  const exitCode = await traceCommand(traceOptions);
+  process.exit(exitCode);
+});
 var updateCheckPromise = null;
 var isJsonOrSummary = process.argv.includes("--json") || process.argv.includes("--summary");
 var isTTY = process.stdout.isTTY === true;
@@ -3096,7 +4228,7 @@ var isDisabledByEnv = !!process.env.NO_UPDATE_NOTIFIER;
 if (!isJsonOrSummary && isTTY && !isDisabledByEnv) {
   updateCheckPromise = (async () => {
     try {
-      const { configLoader: configLoader2 } = await import("./config-2TOQATI3.js");
+      const { configLoader: configLoader2 } = await import("./config-LWUO5EXL.js");
       const configPath = process.argv.indexOf("-c") !== -1 ? process.argv[process.argv.indexOf("-c") + 1] : process.argv.indexOf("--config") !== -1 ? process.argv[process.argv.indexOf("--config") + 1] : void 0;
       const fileConfig = await configLoader2.load(configPath ?? null);
       const updateCheckConfig = fileConfig?.["update-check"];