@ncoderz/awa 1.6.0 → 1.7.1

package/dist/index.js

@@ -16,15 +16,15 @@ import {
   rmDir,
   walkDirectory,
   writeTextFile
-} from "./chunk-ALEGCDAZ.js";
+} from "./chunk-OQZTQ5ZI.js";
 
 // src/cli/index.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
 
 // src/_generated/package_info.ts
 var PACKAGE_INFO = {
   "name": "@ncoderz/awa",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "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."
@@ -121,6 +121,83 @@ function checkCodeAgainstSpec(markers, specs, config) {
       });
     }
   }
+  for (const propId of specs.propertyIds) {
+    if (!testedIds.has(propId)) {
+      const loc = specs.idLocations.get(propId);
+      const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.propertyIds.includes(propId));
+      findings.push({
+        severity: "warning",
+        code: "uncovered-property",
+        message: `Property '${propId}' has no @awa-test reference`,
+        filePath: loc?.filePath ?? specFile?.filePath,
+        line: loc?.line,
+        id: propId
+      });
+    }
+  }
+  const componentFiles = /* @__PURE__ */ new Map();
+  for (const marker of markers.markers) {
+    if (marker.type === "component") {
+      if (!componentFiles.has(marker.id)) {
+        componentFiles.set(marker.id, /* @__PURE__ */ new Set());
+      }
+    }
+  }
+  const fileToComponents = /* @__PURE__ */ new Map();
+  for (const marker of markers.markers) {
+    if (marker.type === "component") {
+      const existing = fileToComponents.get(marker.filePath) ?? [];
+      existing.push(marker.id);
+      fileToComponents.set(marker.filePath, existing);
+    }
+  }
+  for (const marker of markers.markers) {
+    if (marker.type === "impl") {
+      const components = fileToComponents.get(marker.filePath);
+      if (components) {
+        for (const comp of components) {
+          componentFiles.get(comp)?.add(marker.id);
+        }
+      }
+    }
+  }
+  const designImplements = /* @__PURE__ */ new Map();
+  for (const specFile of specs.specFiles) {
+    if (specFile.componentImplements) {
+      for (const [comp, ids] of specFile.componentImplements) {
+        const existing = designImplements.get(comp) ?? /* @__PURE__ */ new Set();
+        for (const id of ids) existing.add(id);
+        designImplements.set(comp, existing);
+      }
+    }
+  }
+  for (const [compName, codeImplIds] of componentFiles) {
+    const designImplIds = designImplements.get(compName);
+    if (!designImplIds) continue;
+    for (const implId of codeImplIds) {
+      if (!designImplIds.has(implId)) {
+        findings.push({
+          severity: "warning",
+          code: "impl-not-in-implements",
+          message: `@awa-impl '${implId}' in component '${compName}' is not listed in its IMPLEMENTS`,
+          id: implId
+        });
+      }
+    }
+    for (const implId of designImplIds) {
+      if (!codeImplIds.has(implId)) {
+        const loc = specs.idLocations.get(compName);
+        findings.push({
+          severity: "warning",
+          code: "implements-not-in-impl",
+          message: `IMPLEMENTS '${implId}' in component '${compName}' has no @awa-impl in code`,
+          filePath: loc?.filePath,
+          line: loc?.line,
+          id: implId
+        });
+      }
+    }
+  }
   return { findings };
 }
 
@@ -259,6 +336,321 @@ async function collectCodeFiles(codeGlobs, ignore) {
   return collectFiles(codeGlobs, ignore);
 }
 
+// src/core/check/matrix-fixer.ts
+import { readFile as readFile2, writeFile } from "fs/promises";
+import { basename } from "path";
+async function fixMatrices(specs, crossRefPatterns) {
+  const codeToReqFile = buildCodeToReqFileMap(specs.specFiles);
+  const fileResults = [];
+  for (const specFile of specs.specFiles) {
+    const fileName = basename(specFile.filePath);
+    if (fileName.startsWith("DESIGN-")) {
+      const changed = await fixDesignMatrix(specFile.filePath, codeToReqFile, crossRefPatterns);
+      fileResults.push({ filePath: specFile.filePath, changed });
+    } else if (fileName.startsWith("TASK-")) {
+      const changed = await fixTaskMatrix(
+        specFile.filePath,
+        codeToReqFile,
+        specs,
+        crossRefPatterns
+      );
+      fileResults.push({ filePath: specFile.filePath, changed });
+    }
+  }
+  return {
+    filesFixed: fileResults.filter((r) => r.changed).length,
+    fileResults
+  };
+}
+function buildCodeToReqFileMap(specFiles) {
+  const map = /* @__PURE__ */ new Map();
+  for (const sf of specFiles) {
+    if (/\bREQ-/.test(basename(sf.filePath)) && sf.code) {
+      map.set(sf.code, basename(sf.filePath));
+    }
+  }
+  return map;
+}
+function getCodePrefix(id) {
+  const match = /^([A-Z][A-Z0-9]*)[-_]/.exec(id);
+  return match?.[1] ?? "";
+}
+async function fixDesignMatrix(filePath, codeToReqFile, crossRefPatterns) {
+  let content;
+  try {
+    content = await readFile2(filePath, "utf-8");
+  } catch {
+    return false;
+  }
+  const { components, properties } = parseDesignFileData(content, crossRefPatterns);
+  const acToComponents = /* @__PURE__ */ new Map();
+  for (const comp of components) {
+    for (const acId of comp.implements) {
+      const existing = acToComponents.get(acId) ?? [];
+      existing.push(comp.name);
+      acToComponents.set(acId, existing);
+    }
+  }
+  const acToProperties = /* @__PURE__ */ new Map();
+  for (const prop of properties) {
+    for (const acId of prop.validates) {
+      const existing = acToProperties.get(acId) ?? [];
+      existing.push(prop.id);
+      acToProperties.set(acId, existing);
+    }
+  }
+  const allAcIds = [...acToComponents.keys()];
+  const grouped = groupByReqFile(allAcIds, codeToReqFile);
+  const newSection = generateDesignSection(grouped, acToComponents, acToProperties);
+  const newContent = replaceTraceabilitySection(content, newSection);
+  if (newContent === content) return false;
+  await writeFile(filePath, newContent, "utf-8");
+  return true;
+}
+function parseDesignFileData(content, crossRefPatterns) {
+  const lines = content.split("\n");
+  const components = [];
+  const properties = [];
+  const componentRegex = /^###\s+([A-Z][A-Z0-9]*-[A-Za-z][A-Za-z0-9]*(?:[A-Z][a-z0-9]*)*)\s*$/;
+  const reqIdRegex = /^###\s+([A-Z][A-Z0-9]*-\d+(?:\.\d+)?)\s*:/;
+  const propIdRegex = /^-\s+([A-Z][A-Z0-9]*_P-\d+)\s/;
+  let currentComponent = null;
+  let lastPropertyId = null;
+  for (const line of lines) {
+    const compMatch = componentRegex.exec(line);
+    if (compMatch?.[1] && !reqIdRegex.test(line)) {
+      currentComponent = compMatch[1];
+      lastPropertyId = null;
+      components.push({ name: currentComponent, implements: [] });
+      continue;
+    }
+    if (/^#{1,2}\s/.test(line) && !compMatch) {
+      currentComponent = null;
+      lastPropertyId = null;
+      continue;
+    }
+    const propMatch = propIdRegex.exec(line);
+    if (propMatch?.[1]) {
+      lastPropertyId = propMatch[1];
+      properties.push({ id: lastPropertyId, validates: [] });
+      continue;
+    }
+    for (const pattern of crossRefPatterns) {
+      const patIdx = line.indexOf(pattern);
+      if (patIdx !== -1) {
+        const afterPattern = line.slice(patIdx + pattern.length);
+        const ids = extractIdsFromText(afterPattern);
+        if (ids.length > 0) {
+          const isImplements = pattern.toLowerCase().includes("implements");
+          if (isImplements && currentComponent) {
+            const comp = components.find((c) => c.name === currentComponent);
+            if (comp) comp.implements.push(...ids);
+          } else if (!isImplements && lastPropertyId) {
+            const prop = properties.find((p) => p.id === lastPropertyId);
+            if (prop) prop.validates.push(...ids);
+          }
+        }
+      }
+    }
+  }
+  return { components, properties };
+}
+function generateDesignSection(grouped, acToComponents, acToProperties) {
+  const lines = [];
+  const reqFiles = [...grouped.keys()].sort();
+  for (const reqFile of reqFiles) {
+    lines.push(`### ${reqFile}`);
+    lines.push("");
+    const acIds = grouped.get(reqFile) ?? [];
+    acIds.sort(compareIds);
+    for (const acId of acIds) {
+      const components = acToComponents.get(acId) ?? [];
+      const props = acToProperties.get(acId) ?? [];
+      for (const comp of components) {
+        const propStr = props.length > 0 ? ` (${props.join(", ")})` : "";
+        lines.push(`- ${acId} \u2192 ${comp}${propStr}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+async function fixTaskMatrix(filePath, codeToReqFile, specs, crossRefPatterns) {
+  let content;
+  try {
+    content = await readFile2(filePath, "utf-8");
+  } catch {
+    return false;
+  }
+  const { tasks, sourceDesigns } = parseTaskFileData(content, crossRefPatterns);
+  const acToTasks = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    for (const acId of task.implements) {
+      const existing = acToTasks.get(acId) ?? [];
+      existing.push(task.id);
+      acToTasks.set(acId, existing);
+    }
+  }
+  const idToTestTasks = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    for (const testId of task.tests) {
+      const existing = idToTestTasks.get(testId) ?? [];
+      existing.push(task.id);
+      idToTestTasks.set(testId, existing);
+    }
+  }
+  const sourcePropertyIds = /* @__PURE__ */ new Set();
+  for (const designName of sourceDesigns) {
+    const designCode = extractCodeFromFileName(designName);
+    for (const sf of specs.specFiles) {
+      if (sf.code === designCode && /\bDESIGN-/.test(basename(sf.filePath))) {
+        for (const propId of sf.propertyIds) sourcePropertyIds.add(propId);
+      }
+    }
+  }
+  const allIdsForMatrix = [.../* @__PURE__ */ new Set([...acToTasks.keys(), ...idToTestTasks.keys()])];
+  const grouped = groupByReqFile(allIdsForMatrix, codeToReqFile);
+  const newSection = generateTaskSection(grouped, acToTasks, idToTestTasks, sourcePropertyIds);
+  const newContent = replaceTraceabilitySection(content, newSection);
+  if (newContent === content) return false;
+  await writeFile(filePath, newContent, "utf-8");
+  return true;
+}
+function parseTaskFileData(content, crossRefPatterns) {
+  const lines = content.split("\n");
+  const tasks = [];
+  const sourceReqs = [];
+  const sourceDesigns = [];
+  const sourceRegex = /^SOURCE:\s*(.+)/;
+  const taskIdRegex = /^-\s+\[[ x]\]\s+(T-[A-Z][A-Z0-9]*-\d+)/;
+  let currentTaskId = null;
+  for (const line of lines) {
+    const sourceMatch = sourceRegex.exec(line);
+    if (sourceMatch?.[1]) {
+      const parts = sourceMatch[1].split(",").map((s) => s.trim());
+      for (const part of parts) {
+        if (part.startsWith("REQ-")) sourceReqs.push(part);
+        else if (part.startsWith("DESIGN-")) sourceDesigns.push(part);
+      }
+      continue;
+    }
+    const taskMatch = taskIdRegex.exec(line);
+    if (taskMatch?.[1]) {
+      currentTaskId = taskMatch[1];
+      tasks.push({ id: currentTaskId, implements: [], tests: [] });
+      continue;
+    }
+    if (/^##\s/.test(line)) {
+      currentTaskId = null;
+      continue;
+    }
+    if (/^---/.test(line)) {
+      currentTaskId = null;
+      continue;
+    }
+    if (currentTaskId) {
+      const task = tasks.find((t) => t.id === currentTaskId);
+      if (task) {
+        for (const pattern of crossRefPatterns) {
+          const patIdx = line.indexOf(pattern);
+          if (patIdx !== -1) {
+            const afterPattern = line.slice(patIdx + pattern.length);
+            const ids = extractIdsFromText(afterPattern);
+            if (ids.length > 0) {
+              const isImplements = pattern.toLowerCase().includes("implements");
+              if (isImplements) {
+                task.implements.push(...ids);
+              }
+            }
+          }
+        }
+        const testsIdx = line.indexOf("TESTS:");
+        if (testsIdx !== -1) {
+          const afterTests = line.slice(testsIdx + "TESTS:".length);
+          const ids = extractIdsFromText(afterTests);
+          if (ids.length > 0) {
+            task.tests.push(...ids);
+          }
+        }
+      }
+    }
+  }
+  return { tasks, sourceReqs, sourceDesigns };
+}
+function generateTaskSection(grouped, acToTasks, idToTestTasks, propertyIds) {
+  const lines = [];
+  const reqFiles = [...grouped.keys()].sort();
+  for (const reqFile of reqFiles) {
+    lines.push(`### ${reqFile}`);
+    lines.push("");
+    const ids = grouped.get(reqFile) ?? [];
+    const acIds = ids.filter((id) => !propertyIds.has(id));
+    const propIds = ids.filter((id) => propertyIds.has(id));
+    acIds.sort(compareIds);
+    propIds.sort(compareIds);
+    for (const acId of acIds) {
+      const tasks = acToTasks.get(acId) ?? [];
+      const testTasks = idToTestTasks.get(acId) ?? [];
+      const taskStr = tasks.length > 0 ? tasks.join(", ") : "(none)";
+      const testStr = testTasks.length > 0 ? ` (${testTasks.join(", ")})` : "";
+      lines.push(`- ${acId} \u2192 ${taskStr}${testStr}`);
+    }
+    for (const propId of propIds) {
+      const testTasks = idToTestTasks.get(propId) ?? [];
+      const testStr = testTasks.length > 0 ? testTasks.join(", ") : "(none)";
+      lines.push(`- ${propId} \u2192 ${testStr}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+function groupByReqFile(ids, codeToReqFile) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    const code = getCodePrefix(id);
+    const reqFile = codeToReqFile.get(code);
+    if (!reqFile) continue;
+    const existing = groups.get(reqFile) ?? [];
+    existing.push(id);
+    groups.set(reqFile, existing);
+  }
+  return groups;
+}
+function replaceTraceabilitySection(content, newSection) {
+  const lines = content.split("\n");
+  const sectionStart = lines.findIndex((l) => /^##\s+Requirements Traceability\s*$/.test(l));
+  if (sectionStart === -1) return content;
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== void 0 && /^##\s/.test(line)) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, sectionStart + 1);
+  const after = lines.slice(sectionEnd);
+  const result = [...before, "", newSection.trimEnd(), "", ...after];
+  return result.join("\n");
+}
+function extractIdsFromText(text) {
+  const idRegex = /[A-Z][A-Z0-9]*-\d+(?:\.\d+)?(?:_AC-\d+)?|[A-Z][A-Z0-9]*_P-\d+/g;
+  const ids = [];
+  let match = idRegex.exec(text);
+  while (match !== null) {
+    ids.push(match[0]);
+    match = idRegex.exec(text);
+  }
+  return ids;
+}
+function extractCodeFromFileName(fileName) {
+  const match = /^(?:REQ|DESIGN|FEAT|EXAMPLES|API|TASK)-([A-Z][A-Z0-9]*)-/.exec(fileName);
+  return match?.[1] ?? "";
+}
+function compareIds(a, b) {
+  return a.localeCompare(b, void 0, { numeric: true });
+}
+
 // src/core/check/reporter.ts
 import chalk from "chalk";
 function report(findings, format) {
@@ -334,7 +726,7 @@ function printRuleContext(f) {
 }
 
 // src/core/check/rule-loader.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { join } from "path";
 import { parse as parseYaml } from "yaml";
 async function loadRules(schemaDir) {
@@ -355,7 +747,7 @@ function matchesTargetGlob(filePath, targetGlob) {
 async function loadRuleFile(filePath) {
   let content;
   try {
-    content = await readFile2(filePath, "utf-8");
+    content = await readFile3(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -547,7 +939,7 @@ var RuleValidationError = class extends Error {
 };
 
 // src/core/check/schema-checker.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
@@ -594,7 +986,7 @@ async function checkSchemasAsync(specFiles, ruleSets) {
     if (matchingRules.length === 0) continue;
     let content;
     try {
-      content = await readFile3(spec.filePath, "utf-8");
+      content = await readFile4(spec.filePath, "utf-8");
     } catch {
       continue;
     }
@@ -1039,8 +1431,8 @@ function collectAllCodeBlocks(section) {
 }
 
 // src/core/check/spec-parser.ts
-import { readFile as readFile4 } from "fs/promises";
-import { basename } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { basename as basename2 } from "path";
 async function parseSpecs(config) {
   const files = await collectSpecFiles(config.specGlobs, config.specIgnore);
   const specFiles = [];
@@ -1068,7 +1460,7 @@ async function parseSpecs(config) {
 async function parseSpecFile(filePath, crossRefPatterns) {
   let content;
   try {
-    content = await readFile4(filePath, "utf-8");
+    content = await readFile5(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -1080,10 +1472,12 @@ async function parseSpecFile(filePath, crossRefPatterns) {
   const componentNames = [];
   const crossRefs = [];
   const idLocations = /* @__PURE__ */ new Map();
+  const componentImplements = /* @__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 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*$/;
+  let currentComponent = null;
   for (const [i, line] of lines.entries()) {
     const lineNum = i + 1;
     const reqMatch = reqIdRegex.exec(line);
@@ -1106,16 +1500,25 @@ async function parseSpecFile(filePath, crossRefPatterns) {
       if (!reqIdRegex.test(line)) {
         componentNames.push(compMatch[1]);
         idLocations.set(compMatch[1], { filePath, line: lineNum });
+        currentComponent = compMatch[1];
       }
     }
+    if (/^#{1,2}\s/.test(line) && !compMatch) {
+      currentComponent = null;
+    }
     for (const pattern of crossRefPatterns) {
       const patIdx = line.indexOf(pattern);
       if (patIdx !== -1) {
         const afterPattern = line.slice(patIdx + pattern.length);
-        const ids = extractIdsFromText(afterPattern);
+        const ids = extractIdsFromText2(afterPattern);
         if (ids.length > 0) {
           const type = pattern.toLowerCase().includes("implements") ? "implements" : "validates";
           crossRefs.push({ type, ids, filePath, line: i + 1 });
+          if (type === "implements" && currentComponent) {
+            const existing = componentImplements.get(currentComponent) ?? [];
+            existing.push(...ids);
+            componentImplements.set(currentComponent, existing);
+          }
         }
       }
     }
@@ -1128,16 +1531,17 @@ async function parseSpecFile(filePath, crossRefPatterns) {
     propertyIds,
     componentNames,
     crossRefs,
-    idLocations
+    idLocations,
+    componentImplements
   };
 }
 function extractCodePrefix(filePath) {
-  const name = basename(filePath, ".md");
+  const name = basename2(filePath, ".md");
   const match = /^(?:REQ|DESIGN|FEAT|EXAMPLES|API)-([A-Z][A-Z0-9]*)-/.exec(name);
   if (match?.[1]) return match[1];
   return "";
 }
-function extractIdsFromText(text) {
+function extractIdsFromText2(text) {
   const idRegex = /[A-Z][A-Z0-9]*-\d+(?:\.\d+)?(?:_AC-\d+)?|[A-Z][A-Z0-9]*_P-\d+/g;
   const ids = [];
   let match = idRegex.exec(text);
@@ -1170,6 +1574,37 @@ function checkSpecAgainstSpec(specs, markers, config) {
       }
     }
   }
+  const implementedAcIds = /* @__PURE__ */ new Set();
+  for (const specFile of specs.specFiles) {
+    for (const crossRef of specFile.crossRefs) {
+      if (crossRef.type === "implements") {
+        for (const id of crossRef.ids) {
+          implementedAcIds.add(id);
+        }
+      }
+    }
+  }
+  const reqAcIds = /* @__PURE__ */ new Set();
+  for (const specFile of specs.specFiles) {
+    if (/\bREQ-/.test(specFile.filePath)) {
+      for (const acId of specFile.acIds) {
+        reqAcIds.add(acId);
+      }
+    }
+  }
+  for (const acId of reqAcIds) {
+    if (!implementedAcIds.has(acId)) {
+      const loc = specs.idLocations.get(acId);
+      findings.push({
+        severity: "error",
+        code: "unlinked-ac",
+        message: `Acceptance criterion '${acId}' is not claimed by any DESIGN IMPLEMENTS`,
+        filePath: loc?.filePath,
+        line: loc?.line,
+        id: acId
+      });
+    }
+  }
   if (!config.specOnly) {
     const referencedCodes = /* @__PURE__ */ new Set();
     for (const marker of markers.markers) {
@@ -1238,7 +1673,8 @@ var DEFAULT_CHECK_CONFIG = {
   schemaDir: ".awa/.agent/schemas",
   schemaEnabled: true,
   allowWarnings: false,
-  specOnly: false
+  specOnly: false,
+  fix: true
 };
 
 // src/commands/check.ts
@@ -1267,7 +1703,20 @@ async function checkCommand(cliOptions) {
     const allFindings = config.allowWarnings ? combinedFindings : combinedFindings.map(
       (f) => f.severity === "warning" ? { ...f, severity: "error" } : f
     );
-    report(allFindings, config.format);
+    const isSummary = cliOptions.summary === true;
+    if (isSummary) {
+      const errors = allFindings.filter((f) => f.severity === "error").length;
+      const warnings = allFindings.filter((f) => f.severity === "warning").length;
+      console.log(`errors: ${errors}, warnings: ${warnings}`);
+    } else {
+      report(allFindings, config.format);
+    }
+    if (config.fix) {
+      const fixResult = await fixMatrices(specs, config.crossRefPatterns);
+      if (fixResult.filesFixed > 0) {
+        logger.info(`Fixed traceability matrices in ${fixResult.filesFixed} file(s)`);
+      }
+    }
     const hasErrors = allFindings.some((f) => f.severity === "error");
     return hasErrors ? 1 : 0;
   } catch (error) {
@@ -1299,11 +1748,12 @@ function buildCheckConfig(fileConfig, cliOptions) {
   const ignoreMarkers = toStringArray(section?.["ignore-markers"]) ?? [
     ...DEFAULT_CHECK_CONFIG.ignoreMarkers
   ];
-  const format = cliOptions.format === "json" ? "json" : section?.format === "json" ? "json" : DEFAULT_CHECK_CONFIG.format;
+  const format = cliOptions.json === true ? "json" : cliOptions.format === "json" ? "json" : section?.format === "json" ? "json" : DEFAULT_CHECK_CONFIG.format;
   const schemaDir = typeof section?.["schema-dir"] === "string" ? section["schema-dir"] : DEFAULT_CHECK_CONFIG.schemaDir;
   const schemaEnabled = typeof section?.["schema-enabled"] === "boolean" ? section["schema-enabled"] : DEFAULT_CHECK_CONFIG.schemaEnabled;
   const allowWarnings = cliOptions.allowWarnings === true ? true : typeof section?.["allow-warnings"] === "boolean" ? section["allow-warnings"] : DEFAULT_CHECK_CONFIG.allowWarnings;
   const specOnly = cliOptions.specOnly === true ? true : typeof section?.["spec-only"] === "boolean" ? section["spec-only"] : DEFAULT_CHECK_CONFIG.specOnly;
+  const fix = cliOptions.fix === false ? false : DEFAULT_CHECK_CONFIG.fix;
   return {
     specGlobs,
     codeGlobs,
@@ -1317,7 +1767,8 @@ function buildCheckConfig(fileConfig, cliOptions) {
     schemaDir,
     schemaEnabled,
     allowWarnings,
-    specOnly
+    specOnly,
+    fix
   };
 }
 function toStringArray(value) {
@@ -2341,8 +2792,8 @@ async function prepareDiff(options) {
 async function diffCommand(cliOptions) {
   try {
     const fileConfig = await configLoader.load(cliOptions.config ?? null);
-    if (cliOptions.all || cliOptions.target) {
-      const mode = cliOptions.all ? "all" : "single";
+    if (cliOptions.allTargets || cliOptions.target) {
+      const mode = cliOptions.allTargets ? "all" : "single";
       const targets = batchRunner.resolveTargets(cliOptions, fileConfig, mode, cliOptions.target);
       let hasDifferences = false;
       for (const { targetName, options: options2 } of targets) {
@@ -2473,7 +2924,7 @@ var FeaturesReporter = class {
 var featuresReporter = new FeaturesReporter();
 
 // src/core/features/scanner.ts
-import { readdir, readFile as readFile5 } from "fs/promises";
+import { readdir, readFile as readFile6 } from "fs/promises";
 import { join as join7, relative as relative3 } from "path";
 var FEATURE_PATTERN = /it\.features\.(?:includes|indexOf)\(\s*['"]([^'"]+)['"]\s*\)/g;
 async function* walkAllFiles(dir) {
@@ -2507,7 +2958,7 @@ var FeatureScanner = class {
     for await (const filePath of walkAllFiles(templatePath)) {
       filesScanned++;
       try {
-        const content = await readFile5(filePath, "utf-8");
+        const content = await readFile6(filePath, "utf-8");
         const flags = this.extractFlags(content);
         const relPath = relative3(templatePath, filePath);
         for (const flag of flags) {
@@ -2532,22 +2983,37 @@ var featureScanner = new FeatureScanner();
 
 // src/commands/features.ts
 async function featuresCommand(cliOptions) {
+  let mergedDir = null;
   try {
-    if (!cliOptions.json) {
+    const silent = cliOptions.json || cliOptions.summary;
+    if (!silent) {
       intro2("awa CLI - Feature Discovery");
     }
     const fileConfig = await configLoader.load(cliOptions.config ?? null);
     const templateSource = cliOptions.template ?? fileConfig?.template ?? null;
     const refresh = cliOptions.refresh ?? fileConfig?.refresh ?? false;
     const template2 = await templateResolver.resolve(templateSource, refresh);
-    const scanResult = await featureScanner.scan(template2.localPath);
+    const overlays = cliOptions.overlay ?? fileConfig?.overlay ?? [];
+    let templatePath = template2.localPath;
+    if (overlays.length > 0) {
+      const overlayDirs = await resolveOverlays(overlays, refresh);
+      mergedDir = await buildMergedDir(template2.localPath, overlayDirs);
+      templatePath = mergedDir;
+    }
+    const scanResult = await featureScanner.scan(templatePath);
     const presets = fileConfig?.presets;
-    featuresReporter.report({
-      scanResult,
-      json: cliOptions.json ?? false,
-      presets
-    });
-    if (!cliOptions.json) {
+    if (cliOptions.summary) {
+      console.log(
+        `features: ${scanResult.features.length}, files-scanned: ${scanResult.filesScanned}`
+      );
+    } else {
+      featuresReporter.report({
+        scanResult,
+        json: cliOptions.json ?? false,
+        presets
+      });
+    }
+    if (!silent) {
       outro2("Feature discovery complete!");
     }
     return 0;
@@ -2558,6 +3024,10 @@ async function featuresCommand(cliOptions) {
       logger.error(String(error));
     }
     return 1;
+  } finally {
+    if (mergedDir) {
+      await rmDir(mergedDir);
+    }
   }
 }
 
@@ -2649,8 +3119,8 @@ async function generateCommand(cliOptions) {
     if (!cliOptions.config && fileConfig === null) {
       logger.info("Tip: create .awa.toml to save your options for next time.");
     }
-    if (cliOptions.all || cliOptions.target) {
-      const mode = cliOptions.all ? "all" : "single";
+    if (cliOptions.allTargets || cliOptions.target) {
+      const mode = cliOptions.allTargets ? "all" : "single";
       const targets = batchRunner.resolveTargets(cliOptions, fileConfig, mode, cliOptions.target);
       for (const { targetName, options: options2 } of targets) {
         batchRunner.logForTarget(targetName, "Starting generation...");
@@ -2684,7 +3154,7 @@ import { intro as intro4, outro as outro4 } from "@clack/prompts";
 
 // src/core/template-test/fixture-loader.ts
 import { readdir as readdir2 } from "fs/promises";
-import { basename as basename2, extname, join as join8 } from "path";
+import { basename as basename3, extname, join as join8 } from "path";
 import { parse } from "smol-toml";
 async function discoverFixtures(templatePath) {
   const testsDir = join8(templatePath, "_tests");
@@ -2706,7 +3176,7 @@ async function discoverFixtures(templatePath) {
 async function parseFixture(filePath) {
   const content = await readTextFile(filePath);
   const parsed = parse(content);
-  const name = basename2(filePath, extname(filePath));
+  const name = basename3(filePath, extname(filePath));
   const features = toStringArray2(parsed.features) ?? [];
   const preset = toStringArray2(parsed.preset) ?? [];
   const removeFeatures = toStringArray2(parsed["remove-features"]) ?? [];
@@ -2729,7 +3199,11 @@ function toStringArray2(value) {
 
 // src/core/template-test/reporter.ts
 import chalk4 from "chalk";
-function report2(result) {
+function report2(result, options) {
+  if (options?.json) {
+    reportJson2(result);
+    return;
+  }
   console.log("");
   for (const fixture of result.results) {
     reportFixture(fixture);
@@ -2743,6 +3217,27 @@ function report2(result) {
   }
   console.log("");
 }
+function reportJson2(result) {
+  const output = {
+    total: result.total,
+    passed: result.passed,
+    failed: result.failed,
+    results: result.results.map((r) => ({
+      name: r.name,
+      passed: r.passed,
+      ...r.error ? { error: r.error } : {},
+      fileResults: r.fileResults.map((f) => ({
+        path: f.path,
+        found: f.found
+      })),
+      snapshotResults: r.snapshotResults.map((s) => ({
+        path: s.path,
+        status: s.status
+      }))
+    }))
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
 function reportFixture(fixture) {
   const icon = fixture.passed ? chalk4.green("\u2714") : chalk4.red("\u2716");
   console.log(`${icon} ${fixture.name}`);
@@ -2905,31 +3400,61 @@ async function runAll(fixtures, templatePath, options, presetDefinitions = {}) {
 
 // src/commands/test.ts
 async function testCommand(options) {
+  let mergedDir = null;
   try {
-    intro4("awa CLI - Template Test");
+    const isJson = options.json === true;
+    const isSummary = options.summary === true;
+    const silent = isJson || isSummary;
+    if (!silent) {
+      intro4("awa CLI - Template Test");
+    }
     const fileConfig = await configLoader.load(options.config ?? null);
     const templateSource = options.template ?? fileConfig?.template ?? null;
-    const template2 = await templateResolver.resolve(templateSource, false);
-    const fixtures = await discoverFixtures(template2.localPath);
+    const refresh = options.refresh ?? false;
+    const template2 = await templateResolver.resolve(templateSource, refresh);
+    const overlays = options.overlay ?? fileConfig?.overlay ?? [];
+    let templatePath = template2.localPath;
+    if (overlays.length > 0) {
+      const overlayDirs = await resolveOverlays(overlays, refresh);
+      mergedDir = await buildMergedDir(template2.localPath, overlayDirs);
+      templatePath = mergedDir;
+    }
+    const fixtures = await discoverFixtures(templatePath);
     if (fixtures.length === 0) {
-      logger.warn("No test fixtures found in _tests/ directory");
-      outro4("No tests to run.");
+      if (isSummary) {
+        console.log("passed: 0, failed: 0, total: 0");
+      } else if (isJson) {
+        console.log(JSON.stringify({ total: 0, passed: 0, failed: 0, results: [] }, null, 2));
+      } else {
+        logger.warn("No test fixtures found in _tests/ directory");
+        outro4("No tests to run.");
+      }
       return 0;
     }
-    logger.info(`Found ${fixtures.length} fixture(s)`);
+    if (!silent) {
+      logger.info(`Found ${fixtures.length} fixture(s)`);
+    }
     const presetDefinitions = fileConfig?.presets ?? {};
     const result = await runAll(
       fixtures,
-      template2.localPath,
+      templatePath,
       { updateSnapshots: options.updateSnapshots },
       presetDefinitions
     );
-    report2(result);
+    if (isSummary) {
+      console.log(`passed: ${result.passed}, failed: ${result.failed}, total: ${result.total}`);
+    } else {
+      report2(result, { json: isJson });
+    }
     if (result.failed > 0) {
-      outro4(`${result.failed} fixture(s) failed.`);
+      if (!silent) {
+        outro4(`${result.failed} fixture(s) failed.`);
+      }
       return 1;
     }
-    outro4("All tests passed!");
+    if (!silent) {
+      outro4("All tests passed!");
+    }
     return 0;
   } catch (error) {
     if (error instanceof Error) {
@@ -2938,11 +3463,15 @@ async function testCommand(options) {
       logger.error(String(error));
     }
     return 2;
+  } finally {
+    if (mergedDir) {
+      await rmDir(mergedDir);
+    }
   }
 }
 
 // src/core/trace/content-assembler.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 var DEFAULT_BEFORE_CONTEXT = 5;
 var DEFAULT_AFTER_CONTEXT = 20;
 async function assembleContent(result, taskPath, contextOptions) {
@@ -3141,7 +3670,7 @@ function findEnclosingBlock(lines, lineIdx, beforeContext = DEFAULT_BEFORE_CONTE
 }
 async function safeReadFile(filePath) {
   try {
-    return await readFile6(filePath, "utf-8");
+    return await readFile7(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -3493,7 +4022,7 @@ function pushToMap(map, key, value) {
 }
 
 // src/core/trace/input-resolver.ts
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 function resolveIds(ids, index) {
   const resolved = [];
   const warnings = [];
@@ -3509,7 +4038,7 @@ function resolveIds(ids, index) {
 async function resolveTaskFile(taskPath, index) {
   let content;
   try {
-    content = await readFile7(taskPath, "utf-8");
+    content = await readFile8(taskPath, "utf-8");
   } catch {
     return { ids: [], warnings: [`Task file not found: ${taskPath}`] };
   }
@@ -3560,7 +4089,7 @@ async function resolveTaskFile(taskPath, index) {
 async function resolveSourceFile(filePath, index) {
   let content;
   try {
-    content = await readFile7(filePath, "utf-8");
+    content = await readFile8(filePath, "utf-8");
   } catch {
     return { ids: [], warnings: [`Source file not found: ${filePath}`] };
   }
@@ -3861,6 +4390,7 @@ function buildScanConfig(fileConfig, overrides) {
     schemaEnabled: false,
     allowWarnings: true,
     specOnly: false,
+    fix: true,
     ...overrides
   };
 }
@@ -3964,6 +4494,13 @@ async function traceCommand(options) {
       }
       return 1;
     }
+    if (options.summary) {
+      const chainCount = result.chains.length;
+      const notFoundCount = result.notFound.length;
+      process.stdout.write(`chains: ${chainCount}, not-found: ${notFoundCount}
+`);
+      return result.notFound.length > 0 && result.chains.length === 0 ? 1 : 0;
+    }
     let output;
     const isContentMode = options.content || options.maxTokens !== void 0;
     const queryLabel = ids.join(", ");
@@ -4063,7 +4600,7 @@ function printUpdateWarning(log, result) {
 }
 
 // src/utils/update-check-cache.ts
-import { mkdir as mkdir3, readFile as readFile8, writeFile } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile9, writeFile as writeFile2 } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join as join11 } from "path";
 var CACHE_DIR = join11(homedir(), ".cache", "awa");
@@ -4071,7 +4608,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 readFile8(CACHE_FILE, "utf-8");
+    const raw = await readFile9(CACHE_FILE, "utf-8");
     const data = JSON.parse(raw);
     if (typeof data.timestamp !== "number" || typeof data.latestVersion !== "string") {
       return true;
@@ -4088,7 +4625,7 @@ async function writeCache(latestVersion) {
       timestamp: Date.now(),
       latestVersion
     };
-    await writeFile(CACHE_FILE, JSON.stringify(data), "utf-8");
+    await writeFile2(CACHE_FILE, JSON.stringify(data), "utf-8");
   } catch {
   }
 }
@@ -4108,7 +4645,7 @@ function configureGenerateCommand(cmd) {
     "--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(
+  ).option("-c, --config <path>", "Path to configuration file").option("--refresh", "Force refresh of cached Git templates", false).option("--all-targets", "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) => {
@@ -4123,7 +4660,8 @@ function configureGenerateCommand(cmd) {
       delete: options.delete,
       config: options.config,
       refresh: options.refresh,
-      all: options.all,
+      all: options.allTargets,
+      allTargets: options.allTargets,
       target: options.target,
       overlay: options.overlay || [],
       json: options.json,
@@ -4137,7 +4675,7 @@ 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) => {
+).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-targets", "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) => {
   const cliOptions = {
     output: target,
     // Use target as output for consistency
@@ -4148,7 +4686,8 @@ template.command("diff").description("Compare template output with existing targ
     config: options.config,
     refresh: options.refresh,
     listUnknown: options.listUnknown,
-    all: options.all,
+    all: options.allTargets,
+    allTargets: options.allTargets,
     target: options.target,
     watch: options.watch,
     overlay: options.overlay || [],
@@ -4160,7 +4699,9 @@ template.command("diff").description("Compare template output with existing targ
 });
 program.command("check").description(
   "Validate spec files against schemas and check traceability between code markers and specs"
-).option("-c, --config <path>", "Path to configuration file").option("--spec-ignore <pattern...>", "Glob patterns to exclude from spec file scanning").option("--code-ignore <pattern...>", "Glob patterns to exclude from code file scanning").option("--format <format>", "Output format (text or json)", "text").option(
+).option("-c, --config <path>", "Path to configuration file").option("--spec-ignore <pattern...>", "Glob patterns to exclude from spec file scanning").option("--code-ignore <pattern...>", "Glob patterns to exclude from code file scanning").option("--json", "Output results as JSON", false).addOption(
+  new Option("--format <format>", "Output format (text or json)").default("text").hideHelp()
+).option("--summary", "Output compact one-line summary", false).option(
   "--allow-warnings",
   "Allow warnings without failing (default: warnings are errors)",
   false
@@ -4168,38 +4709,50 @@ program.command("check").description(
   "--spec-only",
   "Run only spec-level checks (schema and cross-refs); skip code-to-spec traceability",
   false
+).option(
+  "--no-fix",
+  "Skip regeneration of Requirements Traceability sections in DESIGN and TASK files"
 ).action(async (options) => {
   const cliOptions = {
     config: options.config,
     specIgnore: options.specIgnore,
     codeIgnore: options.codeIgnore,
     format: options.format,
+    json: options.json,
+    summary: options.summary,
     allowWarnings: options.allowWarnings,
-    specOnly: options.specOnly
+    specOnly: options.specOnly,
+    fix: options.fix
   };
   const exitCode = await checkCommand(cliOptions);
   process.exit(exitCode);
 });
-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) => {
+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("--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 (options) => {
   const exitCode = await featuresCommand({
     template: options.template,
     config: options.config,
     refresh: options.refresh,
-    json: options.json
+    json: options.json,
+    summary: options.summary,
+    overlay: options.overlay || []
   });
   process.exit(exitCode);
 });
-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) => {
+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).option("--refresh", "Force refresh of cached Git templates", 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 (options) => {
   const testOptions = {
     template: options.template,
     config: options.config,
-    updateSnapshots: options.updateSnapshots
+    updateSnapshots: options.updateSnapshots,
+    refresh: options.refresh,
+    json: options.json,
+    summary: options.summary,
+    overlay: options.overlay || []
   };
   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) => {
+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 results as JSON", false).option("--summary", "Output compact one-line summary", 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,
@@ -4208,6 +4761,7 @@ program.command("trace").description("Explore traceability chains and assemble c
     content: options.content,
     list: options.list,
     json: options.json,
+    summary: options.summary,
     maxTokens: options.maxTokens !== void 0 ? Number(options.maxTokens) : void 0,
     depth: options.depth !== void 0 ? Number(options.depth) : void 0,
     scope: options.scope,
@@ -4228,7 +4782,7 @@ var isDisabledByEnv = !!process.env.NO_UPDATE_NOTIFIER;
 if (!isJsonOrSummary && isTTY && !isDisabledByEnv) {
   updateCheckPromise = (async () => {
     try {
-      const { configLoader: configLoader2 } = await import("./config-LWUO5EXL.js");
+      const { configLoader: configLoader2 } = await import("./config-WL3SLSP6.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"];