@ncoderz/awa 1.8.4 → 1.9.0

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   renumberCommand,
   scan,
   scanMarkers
-} from "./chunk-2VUVSW6T.js";
+} from "./chunk-PC3PMV3K.js";
 import {
   ConfigError,
   DiffError,
@@ -28,7 +28,7 @@ import {
   rmDir,
   walkDirectory,
   writeTextFile
-} from "./chunk-GOIBZQFJ.js";
+} from "./chunk-4NC73OUR.js";
 
 // src/cli/index.ts
 import { Command, Option } from "commander";
@@ -36,14 +36,42 @@ import { Command, Option } from "commander";
 // src/_generated/package_info.ts
 var PACKAGE_INFO = {
   "name": "@ncoderz/awa",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "author": "Richard Sewell <richard.sewell@ncoderz.com>",
   "license": "BSD-3-Clause",
   "description": "awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage agent workflow files using templates."
 };
 
 // src/core/check/code-spec-checker.ts
-function checkCodeAgainstSpec(markers, specs, config) {
+function buildComponentAttribution(markers) {
+  const result = /* @__PURE__ */ new Map();
+  for (const m of markers) {
+    if (m.type === "component" && !result.has(m.id)) {
+      result.set(m.id, /* @__PURE__ */ new Set());
+    }
+  }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const m of markers) {
+    const list = byFile.get(m.filePath) ?? [];
+    list.push(m);
+    byFile.set(m.filePath, list);
+  }
+  for (const fileMarkers of byFile.values()) {
+    const sorted = [...fileMarkers].sort((a, b) => a.line - b.line);
+    let activeComponent = null;
+    for (const m of sorted) {
+      if (m.type === "component") {
+        activeComponent = m.id;
+      } else {
+        if (activeComponent) {
+          result.get(activeComponent)?.add(m.id);
+        }
+      }
+    }
+  }
+  return result;
+}
+function checkCodeAgainstSpec(markers, specs, config, deprecatedIds = /* @__PURE__ */ new Set()) {
   const findings = [];
   const idRegex = new RegExp(`^${config.idPattern}$`);
   for (const marker of markers.markers) {
@@ -64,6 +92,19 @@ function checkCodeAgainstSpec(markers, specs, config) {
   for (const marker of markers.markers) {
     if (marker.type === "component") {
       if (!specs.componentNames.has(marker.id)) {
+        if (deprecatedIds.has(marker.id)) {
+          if (config.deprecated) {
+            findings.push({
+              severity: "warning",
+              code: "deprecated-ref",
+              message: `Component marker '${marker.id}' references a deprecated ID`,
+              filePath: marker.filePath,
+              line: marker.line,
+              id: marker.id
+            });
+          }
+          continue;
+        }
         findings.push({
           severity: "error",
           code: "orphaned-marker",
@@ -75,6 +116,19 @@ function checkCodeAgainstSpec(markers, specs, config) {
       }
     } else {
       if (!specs.allIds.has(marker.id)) {
+        if (deprecatedIds.has(marker.id)) {
+          if (config.deprecated) {
+            findings.push({
+              severity: "warning",
+              code: "deprecated-ref",
+              message: `Marker '${marker.id}' references a deprecated ID`,
+              filePath: marker.filePath,
+              line: marker.line,
+              id: marker.id
+            });
+          }
+          continue;
+        }
         findings.push({
           severity: "error",
           code: "orphaned-marker",
@@ -88,6 +142,7 @@ function checkCodeAgainstSpec(markers, specs, config) {
   }
   const testedIds = new Set(markers.markers.filter((m) => m.type === "test").map((m) => m.id));
   for (const acId of specs.acIds) {
+    if (deprecatedIds.has(acId)) continue;
     if (!testedIds.has(acId)) {
       const loc = specs.idLocations.get(acId);
       const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.acIds.includes(acId));
@@ -105,6 +160,7 @@ function checkCodeAgainstSpec(markers, specs, config) {
     markers.markers.filter((m) => m.type === "component").map((m) => m.id)
   );
   for (const componentName of specs.componentNames) {
+    if (deprecatedIds.has(componentName)) continue;
     if (!implementedComponents.has(componentName)) {
       const loc = specs.idLocations.get(componentName);
       const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.componentNames.includes(componentName));
@@ -120,6 +176,7 @@ function checkCodeAgainstSpec(markers, specs, config) {
   }
   const implementedIds = new Set(markers.markers.filter((m) => m.type === "impl").map((m) => m.id));
   for (const acId of specs.acIds) {
+    if (deprecatedIds.has(acId)) continue;
     if (!implementedIds.has(acId)) {
       const loc = specs.idLocations.get(acId);
       const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.acIds.includes(acId));
@@ -134,6 +191,7 @@ function checkCodeAgainstSpec(markers, specs, config) {
     }
   }
   for (const propId of specs.propertyIds) {
+    if (deprecatedIds.has(propId)) continue;
     if (!testedIds.has(propId)) {
       const loc = specs.idLocations.get(propId);
       const specFile = loc ? void 0 : specs.specFiles.find((sf) => sf.propertyIds.includes(propId));
@@ -147,32 +205,7 @@ function checkCodeAgainstSpec(markers, specs, config) {
       });
     }
   }
-  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 componentFiles = buildComponentAttribution(markers.markers);
   const designImplements = /* @__PURE__ */ new Map();
   for (const specFile of specs.specFiles) {
     if (specFile.componentImplements) {
@@ -514,8 +547,37 @@ function replaceFeatureCodesSection(content, sectionStart, newSection) {
   return result.join("\n");
 }
 
+// src/core/check/deprecated-parser.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join } from "path";
+var DEPRECATED_PATH = "deprecated/DEPRECATED.md";
+async function parseDeprecated(specDir) {
+  const filePath = join(specDir, DEPRECATED_PATH);
+  let content;
+  try {
+    content = await readFile3(filePath, "utf-8");
+  } catch {
+    return { deprecatedIds: /* @__PURE__ */ new Set() };
+  }
+  const deprecatedIds = /* @__PURE__ */ new Set();
+  const idPattern = /[A-Z][A-Z0-9]*(?:-\d+(?:\.\d+)?(?:_AC-\d+)?|_P-\d+|-[A-Za-z][A-Za-z0-9]*)/g;
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || /^#\s/.test(trimmed)) continue;
+    for (const segment of trimmed.split(",")) {
+      const match = segment.trim().match(idPattern);
+      if (match) {
+        for (const id of match) {
+          deprecatedIds.add(id);
+        }
+      }
+    }
+  }
+  return { deprecatedIds };
+}
+
 // src/core/check/matrix-fixer.ts
-import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
 import { basename as basename3 } from "path";
 async function fixMatrices(specs, crossRefPatterns) {
   const reqFileMaps = buildReqFileMaps(specs.specFiles);
@@ -590,7 +652,7 @@ async function fixDesignMatrix(filePath, reqFileMaps, crossRefPatterns, cachedCo
     content = cachedContent;
   } else {
     try {
-      content = await readFile3(filePath, "utf-8");
+      content = await readFile4(filePath, "utf-8");
     } catch {
       return false;
     }
@@ -694,7 +756,7 @@ async function fixTaskMatrix(filePath, reqFileMaps, specs, crossRefPatterns, cac
     content = cachedContent;
   } else {
     try {
-      content = await readFile3(filePath, "utf-8");
+      content = await readFile4(filePath, "utf-8");
     } catch {
       return false;
     }
@@ -941,12 +1003,31 @@ function printRuleContext(f) {
   console.log(chalk.dim(`      rule: ${parts.join(" \u2014 ")}`));
 }
 
+// src/core/check/reservation-checker.ts
+function checkReservations(specs, deprecatedIds) {
+  const findings = [];
+  for (const id of deprecatedIds) {
+    if (specs.allIds.has(id)) {
+      const loc = specs.idLocations.get(id);
+      findings.push({
+        severity: "error",
+        code: "deprecated-id-conflict",
+        message: `ID '${id}' is defined in active specs but is reserved by the deprecated file`,
+        filePath: loc?.filePath,
+        line: loc?.line,
+        id
+      });
+    }
+  }
+  return { findings };
+}
+
 // src/core/check/rule-loader.ts
-import { readFile as readFile4 } from "fs/promises";
-import { join } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join2 } from "path";
 import { parse as parseYaml } from "yaml";
 async function loadRules(schemaDir) {
-  const pattern = join(schemaDir, "*.schema.yaml");
+  const pattern = join2(schemaDir, "*.schema.yaml");
   const files = await collectFiles([pattern], []);
   const results = [];
   for (const filePath of files) {
@@ -963,7 +1044,7 @@ function matchesTargetGlob(filePath, targetGlob) {
 async function loadRuleFile(filePath) {
   let content;
   try {
-    content = await readFile4(filePath, "utf-8");
+    content = await readFile5(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -1155,7 +1236,7 @@ var RuleValidationError = class extends Error {
 };
 
 // src/core/check/schema-checker.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
@@ -1205,7 +1286,7 @@ async function checkSchemasAsync(specFiles, ruleSets) {
       content = spec2.content;
     } else {
       try {
-        content = await readFile5(spec2.filePath, "utf-8");
+        content = await readFile6(spec2.filePath, "utf-8");
       } catch {
         continue;
       }
@@ -1651,12 +1732,25 @@ function collectAllCodeBlocks(section) {
 }
 
 // src/core/check/spec-spec-checker.ts
-function checkSpecAgainstSpec(specs, markers, config) {
+function checkSpecAgainstSpec(specs, markers, config, deprecatedIds = /* @__PURE__ */ new Set()) {
   const findings = [];
   for (const specFile of specs.specFiles) {
     for (const crossRef of specFile.crossRefs) {
       for (const refId of crossRef.ids) {
         if (!specs.allIds.has(refId)) {
+          if (deprecatedIds.has(refId)) {
+            if (config.deprecated) {
+              findings.push({
+                severity: "warning",
+                code: "deprecated-ref",
+                message: `Cross-reference '${refId}' (${crossRef.type}) targets a deprecated ID`,
+                filePath: crossRef.filePath,
+                line: crossRef.line,
+                id: refId
+              });
+            }
+            continue;
+          }
           findings.push({
             severity: "error",
             code: "broken-cross-ref",
@@ -1687,7 +1781,16 @@ function checkSpecAgainstSpec(specs, markers, config) {
       }
     }
   }
+  const deprecatedReqIds = /* @__PURE__ */ new Set();
+  for (const id of deprecatedIds) {
+    if (/^[A-Z][A-Z0-9]*-\d+(?:\.\d+)?$/.test(id)) {
+      deprecatedReqIds.add(id);
+    }
+  }
   for (const acId of reqAcIds) {
+    if (deprecatedIds.has(acId)) continue;
+    const parentMatch = /^([A-Z][A-Z0-9]*-\d+(?:\.\d+)?)_AC-\d+$/.exec(acId);
+    if (parentMatch?.[1] && deprecatedReqIds.has(parentMatch[1])) continue;
     if (!implementedAcIds.has(acId)) {
       const loc = specs.idLocations.get(acId);
       findings.push({
@@ -1748,8 +1851,10 @@ async function checkCommand(cliOptions) {
       parseSpecs(config),
       config.schemaEnabled ? loadRules(config.schemaDir) : Promise.resolve([])
     ]);
-    const codeSpecResult = config.specOnly ? { findings: [] } : checkCodeAgainstSpec(markers, specs, config);
-    const specSpecResult = checkSpecAgainstSpec(specs, markers, config);
+    const { deprecatedIds } = await parseDeprecated(".awa/specs");
+    const codeSpecResult = config.specOnly ? { findings: [] } : checkCodeAgainstSpec(markers, specs, config, deprecatedIds);
+    const specSpecResult = checkSpecAgainstSpec(specs, markers, config, deprecatedIds);
+    const reservationResult = deprecatedIds.size > 0 ? checkReservations(specs, deprecatedIds) : { findings: [] };
     if (config.fix) {
       const fixResult = await fixMatrices(specs, config.crossRefPatterns);
       if (fixResult.filesFixed > 0) {
@@ -1770,6 +1875,7 @@ async function checkCommand(cliOptions) {
       ...markers.findings,
       ...codeSpecResult.findings,
       ...specSpecResult.findings,
+      ...reservationResult.findings,
       ...schemaResult.findings
     ];
     const allFindings = config.allowWarnings ? combinedFindings : combinedFindings.map(
@@ -1820,6 +1926,7 @@ function buildCheckConfig(fileConfig, cliOptions) {
   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;
+  const deprecated = cliOptions.deprecated === true ? true : DEFAULT_CHECK_CONFIG.deprecated;
   const extraSpecGlobs = toStringArray(section?.["extra-spec-globs"]) ?? [
     ...DEFAULT_CHECK_CONFIG.extraSpecGlobs
   ];
@@ -1842,7 +1949,8 @@ function buildCheckConfig(fileConfig, cliOptions) {
     schemaEnabled,
     allowWarnings,
     specOnly,
-    fix
+    fix,
+    deprecated
   };
 }
 function toStringArray(value) {
@@ -1991,6 +2099,9 @@ var BatchRunner = class {
     }
     return results;
   }
+  // @awa-component: MULTI-Reporter
+  // @awa-impl: MULTI-4_AC-1, MULTI-4_AC-2, MULTI-5_AC-1
+  // @awa-impl: MULTI-8_AC-1, MULTI-9_AC-1, MULTI-11_AC-1
   // Log a message prefixed with target name
   logForTarget(targetName, message) {
     logger.info(`[${targetName}] ${message}`);
@@ -2006,12 +2117,12 @@ var batchRunner = new BatchRunner();
 
 // src/core/differ.ts
 import { tmpdir } from "os";
-import { join as join4, relative as relative2 } from "path";
+import { join as join5, relative as relative2 } from "path";
 import { structuredPatch } from "diff";
 import { isBinaryFile as detectBinaryFile } from "isbinaryfile";
 
 // src/core/delete-list.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 var DELETE_LIST_FILENAME = "_delete.txt";
 function parseDeleteList(content) {
   const entries = [];
@@ -2038,7 +2149,7 @@ function resolveDeleteList(entries, activeFeatures) {
   return entries.filter((e) => e.features === void 0 || !e.features.some((f) => activeSet.has(f))).map((e) => e.path);
 }
 async function loadDeleteList(templatePath) {
-  const deleteListPath = join2(templatePath, DELETE_LIST_FILENAME);
+  const deleteListPath = join3(templatePath, DELETE_LIST_FILENAME);
   if (!await pathExists(deleteListPath)) {
     return [];
   }
@@ -2047,7 +2158,7 @@ async function loadDeleteList(templatePath) {
 }
 
 // src/core/generator.ts
-import { join as join3, relative } from "path";
+import { join as join4, relative } from "path";
 
 // src/core/resolver.ts
 import { MultiSelectPrompt } from "@clack/core";
@@ -2117,8 +2228,9 @@ ${chalk3.cyan(_BAR_END)}
 var ConflictResolver = class {
   // @awa-impl: GEN-4_AC-1, GEN-4_AC-2, GEN-4_AC-3
   // @awa-impl: GEN-5_AC-1, GEN-5_AC-2, GEN-5_AC-3, GEN-5_AC-4, GEN-5_AC-5, GEN-5_AC-6, GEN-5_AC-7
-  // @awa-impl: CLI-5_AC-2, CLI-5_AC-3
-  // @awa-impl: GEN-6_AC-3
+  // @awa-impl: CLI-5_AC-2, CLI-5_AC-3, CLI-12_AC-3
+  // @awa-impl: GEN-6_AC-3, GEN-10_AC-3
+  // @awa-impl: GEN-12_AC-3, GEN-12_AC-4, GEN-12_AC-5
   async resolveBatch(conflicts, force, dryRun) {
     const identicalPaths = conflicts.filter((c) => c.newContent === c.existingContent).map((c) => c.outputPath);
     const differentFiles = conflicts.filter((c) => c.newContent !== c.existingContent);
@@ -2171,6 +2283,11 @@ var DeleteResolver = class {
    * Prompt user to confirm which files to delete.
    * Returns the list of absolute paths confirmed for deletion.
    */
+  // @awa-impl: GEN-12_AC-3, GEN-12_AC-4, GEN-12_AC-5, CLI-12_AC-3
+  // @awa-impl: CLI-5_AC-2, CLI-5_AC-3
+  // @awa-impl: GEN-4_AC-1, GEN-4_AC-2, GEN-4_AC-3
+  // @awa-impl: GEN-5_AC-1, GEN-5_AC-2, GEN-5_AC-3, GEN-5_AC-4, GEN-5_AC-5, GEN-5_AC-6, GEN-5_AC-7
+  // @awa-impl: GEN-6_AC-3, GEN-10_AC-3
   async resolveDeletes(candidates, force, dryRun) {
     if (candidates.length === 0) {
       return [];
@@ -2376,7 +2493,7 @@ var FileGenerator = class {
         const generatedOutputPaths = new Set(filesToProcess.map((f) => f.outputFile));
         const deleteCandidates = [];
         for (const relPath of deleteList) {
-          const absPath = join3(outputPath, relPath);
+          const absPath = join4(outputPath, relPath);
           if (generatedOutputPaths.has(absPath)) {
             logger.warn(
               `Delete list entry '${relPath}' conflicts with generated file \u2014 skipping deletion`
@@ -2438,7 +2555,7 @@ var FileGenerator = class {
   // @awa-impl: GEN-1_AC-1, GEN-1_AC-2, GEN-1_AC-3
   computeOutputPath(templatePath, templateRoot, outputRoot) {
     const relativePath = relative(templateRoot, templatePath);
-    return join3(outputRoot, relativePath);
+    return join4(outputRoot, relativePath);
   }
 };
 var fileGenerator = new FileGenerator();
@@ -2480,8 +2597,8 @@ var DiffEngine = class {
       }
       const files = [];
       for (const relPath of generatedFiles) {
-        const generatedFilePath = join4(tempPath, relPath);
-        const targetFilePath = join4(targetPath, relPath);
+        const generatedFilePath = join5(tempPath, relPath);
+        const targetFilePath = join5(targetPath, relPath);
         if (targetFiles.has(relPath)) {
           const fileDiff = await this.compareFiles(generatedFilePath, targetFilePath, relPath);
           files.push(fileDiff);
@@ -2545,7 +2662,7 @@ var DiffEngine = class {
     const systemTemp = tmpdir();
     const timestamp = Date.now();
     const random = Math.random().toString(36).substring(2, 8);
-    const tempPath = join4(systemTemp, `awa-diff-${timestamp}-${random}`);
+    const tempPath = join5(systemTemp, `awa-diff-${timestamp}-${random}`);
     await ensureDir(tempPath);
     return tempPath;
   }
@@ -2698,18 +2815,18 @@ function writeJsonOutput(data) {
 // src/core/overlay.ts
 import { cp } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/core/template-resolver.ts
 import { createHash } from "crypto";
 import { rm } from "fs/promises";
-import { isAbsolute, join as join5, resolve } from "path";
+import { isAbsolute, join as join6, resolve } from "path";
 import degit from "degit";
 var TemplateResolver = class {
   // @awa-impl: CLI-3_AC-2, TPL-10_AC-1
   async resolve(source, refresh) {
     if (!source) {
-      const bundledPath = join5(getTemplateDir(), "awa");
+      const bundledPath = join6(getTemplateDir(), "awa");
       return {
         type: "bundled",
         localPath: bundledPath,
@@ -2786,7 +2903,7 @@ var TemplateResolver = class {
   getCachePath(source) {
     const hash = createHash("sha256").update(source).digest("hex").substring(0, 16);
     const cacheDir = getCacheDir();
-    return join5(cacheDir, hash);
+    return join6(cacheDir, hash);
   }
 };
 var templateResolver = new TemplateResolver();
@@ -2803,7 +2920,7 @@ async function resolveOverlays(overlays, refresh) {
 async function buildMergedDir(baseDir, overlayDirs) {
   const timestamp = Date.now();
   const random = Math.random().toString(36).substring(2, 8);
-  const tempPath = join6(tmpdir2(), `awa-overlay-${timestamp}-${random}`);
+  const tempPath = join7(tmpdir2(), `awa-overlay-${timestamp}-${random}`);
   await ensureDir(tempPath);
   await cp(baseDir, tempPath, { recursive: true });
   for (const overlayDir of overlayDirs) {
@@ -3088,13 +3205,13 @@ var FeaturesReporter = class {
 var featuresReporter = new FeaturesReporter();
 
 // src/core/features/scanner.ts
-import { readdir, readFile as readFile6 } from "fs/promises";
-import { join as join7, relative as relative3 } from "path";
+import { readdir, readFile as readFile7 } from "fs/promises";
+import { join as join8, relative as relative3 } from "path";
 var FEATURE_PATTERN = /it\.features\.(?:includes|indexOf)\(\s*['"]([^'"]+)['"]\s*\)/g;
 async function* walkAllFiles(dir) {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join7(dir, entry.name);
+    const fullPath = join8(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkAllFiles(fullPath);
     } else if (entry.isFile()) {
@@ -3122,7 +3239,7 @@ var FeatureScanner = class {
     for await (const filePath of walkAllFiles(templatePath)) {
       filesScanned++;
       try {
-        const content = await readFile6(filePath, "utf-8");
+        const content = await readFile7(filePath, "utf-8");
         const flags = this.extractFlags(content);
         const relPath = relative3(templatePath, filePath);
         for (const flag of flags) {
@@ -3314,21 +3431,21 @@ async function generateCommand(cliOptions) {
 }
 
 // src/core/merge/content-merger.ts
-import { readFile as readFile7, rename, writeFile as writeFile3 } from "fs/promises";
-import { basename as basename4, dirname, extname, join as join8 } from "path";
+import { readFile as readFile8, rename, writeFile as writeFile3 } from "fs/promises";
+import { basename as basename4, dirname, extname, join as join9 } from "path";
 var MERGE_PREFIXES = ["FEAT", "REQ", "DESIGN", "API", "EXAMPLE", "TASK"];
 function resolveMovePath(sourceFilePath, prefix, sourceCode, targetCode, existingPaths, plannedPaths) {
   const dir = dirname(sourceFilePath);
   const name = basename4(sourceFilePath);
   const newName = name.replace(`${prefix}-${sourceCode}-`, `${prefix}-${targetCode}-`);
-  const newPath = join8(dir, newName);
+  const newPath = join9(dir, newName);
   if (!existingPaths.has(newPath) && !plannedPaths.has(newPath)) {
     return newPath;
   }
   const ext = extname(newName);
   const stem = newName.slice(0, -ext.length);
   for (let i = 1; i < 1e3; i++) {
-    const indexed = join8(dir, `${stem}-${String(i).padStart(3, "0")}${ext}`);
+    const indexed = join9(dir, `${stem}-${String(i).padStart(3, "0")}${ext}`);
     if (!existingPaths.has(indexed) && !plannedPaths.has(indexed)) {
       return indexed;
     }
@@ -3387,7 +3504,7 @@ async function executeMoves(sourceCode, targetCode, specFiles, dryRun) {
       docType: matchedPrefix
     });
     if (!dryRun) {
-      const content = await readFile7(sf.filePath, "utf-8");
+      const content = await readFile8(sf.filePath, "utf-8");
       const updated = updateHeading(content, sourceCode, targetCode);
       await rename(sf.filePath, targetPath);
       if (updated !== content) {
@@ -3470,8 +3587,8 @@ function formatJson2(result) {
 }
 
 // src/core/merge/spec-mover.ts
-import { readFile as readFile8, rename as rename2 } from "fs/promises";
-import { basename as basename5, dirname as dirname2, join as join9 } from "path";
+import { readFile as readFile9, rename as rename2 } from "fs/promises";
+import { basename as basename5, dirname as dirname2, join as join10 } from "path";
 
 // src/core/merge/types.ts
 var MergeError = class extends Error {
@@ -3504,7 +3621,7 @@ function planRenames(sourceCode, targetCode, specFiles) {
         const oldSuffix = name.slice(oldPrefix.length);
         const newSuffix = targetFeature ? replaceFeaturePart(oldSuffix, targetFeature) : oldSuffix;
         const newName = `${prefix}-${targetCode}-${newSuffix}`;
-        const newPath = join9(dirname2(sf.filePath), newName);
+        const newPath = join10(dirname2(sf.filePath), newName);
         renames.push({ oldPath: sf.filePath, newPath });
         break;
       }
@@ -3546,7 +3663,7 @@ function updateHeading2(content, sourceCode, targetCode) {
 async function executeRenames(renames, sourceCode, targetCode, dryRun) {
   if (dryRun) return renames;
   for (const r of renames) {
-    const content = await readFile8(r.oldPath, "utf-8");
+    const content = await readFile9(r.oldPath, "utf-8");
     const updated = updateHeading2(content, sourceCode, targetCode);
     await rename2(r.oldPath, r.newPath);
     if (updated !== content) {
@@ -3562,7 +3679,7 @@ async function findStaleRefs(sourceCode, filePaths) {
   for (const filePath of filePaths) {
     let content;
     try {
-      content = await readFile8(filePath, "utf-8");
+      content = await readFile9(filePath, "utf-8");
     } catch {
       continue;
     }
@@ -3775,7 +3892,7 @@ async function mergeCommand(options) {
       return 2;
     }
     if (options.renumber && !dryRun && !noChange) {
-      const { renumberCommand: renumberCommand2 } = await import("./renumber-TGDI47IS.js");
+      const { renumberCommand: renumberCommand2 } = await import("./renumber-LG6FUVOP.js");
       await renumberCommand2({
         code: options.targetCode,
         dryRun: false,
@@ -3963,10 +4080,10 @@ 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 basename6, extname as extname2, join as join10 } from "path";
+import { basename as basename6, extname as extname2, join as join11 } from "path";
 import { parse } from "smol-toml";
 async function discoverFixtures(templatePath) {
-  const testsDir = join10(templatePath, "_tests");
+  const testsDir = join11(templatePath, "_tests");
   let entries;
   try {
     const dirEntries = await readdir2(testsDir, { withFileTypes: true });
@@ -3976,7 +4093,7 @@ async function discoverFixtures(templatePath) {
   }
   const fixtures = [];
   for (const filename of entries) {
-    const filePath = join10(testsDir, filename);
+    const filePath = join11(testsDir, filename);
     const fixture = await parseFixture(filePath);
     fixtures.push(fixture);
   }
@@ -4077,16 +4194,16 @@ function reportFixture(fixture) {
 // src/core/template-test/runner.ts
 import { mkdir as mkdir2, rm as rm3 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 
 // src/core/template-test/snapshot.ts
 import { mkdir, readdir as readdir3, rm as rm2 } from "fs/promises";
-import { join as join11, relative as relative4 } from "path";
+import { join as join12, relative as relative4 } from "path";
 async function walkRelative(dir, base) {
   const results = [];
   const entries = await readdir3(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join11(dir, entry.name);
+    const fullPath = join12(dir, entry.name);
     if (entry.isDirectory()) {
       const sub = await walkRelative(fullPath, base);
       results.push(...sub);
@@ -4103,8 +4220,8 @@ async function compareSnapshots(renderedDir, snapshotDir) {
   const snapshotSet = new Set(snapshotFiles);
   const renderedSet = new Set(renderedFiles);
   for (const file of renderedFiles) {
-    const renderedPath = join11(renderedDir, file);
-    const snapshotPath = join11(snapshotDir, file);
+    const renderedPath = join12(renderedDir, file);
+    const snapshotPath = join12(snapshotDir, file);
     if (!snapshotSet.has(file)) {
       results.push({ path: file, status: "missing-snapshot" });
       continue;
@@ -4130,8 +4247,8 @@ async function updateSnapshots(renderedDir, snapshotDir) {
   await mkdir(snapshotDir, { recursive: true });
   const files = await walkRelative(renderedDir, renderedDir);
   for (const file of files) {
-    const srcPath = join11(renderedDir, file);
-    const destPath = join11(snapshotDir, file);
+    const srcPath = join12(renderedDir, file);
+    const destPath = join12(snapshotDir, file);
     const content = await readTextFile(srcPath);
     await writeTextFile(destPath, content);
   }
@@ -4139,7 +4256,7 @@ async function updateSnapshots(renderedDir, snapshotDir) {
 
 // src/core/template-test/runner.ts
 async function runFixture(fixture, templatePath, options, presetDefinitions = {}) {
-  const tempDir = join12(tmpdir3(), `awa-test-${fixture.name}-${Date.now()}`);
+  const tempDir = join13(tmpdir3(), `awa-test-${fixture.name}-${Date.now()}`);
   try {
     await mkdir2(tempDir, { recursive: true });
     const features = featureResolver.resolve({
@@ -4158,12 +4275,12 @@ async function runFixture(fixture, templatePath, options, presetDefinitions = {}
     });
     const fileResults = [];
     for (const expectedFile of fixture.expectedFiles) {
-      const fullPath = join12(tempDir, expectedFile);
+      const fullPath = join13(tempDir, expectedFile);
       const found = await pathExists(fullPath);
       fileResults.push({ path: expectedFile, found });
     }
     const missingFiles = fileResults.filter((r) => !r.found);
-    const snapshotDir = join12(templatePath, "_tests", fixture.name);
+    const snapshotDir = join13(templatePath, "_tests", fixture.name);
     let snapshotResults = [];
     if (options.updateSnapshots) {
       await updateSnapshots(tempDir, snapshotDir);
@@ -4280,7 +4397,7 @@ async function testCommand(options) {
 }
 
 // src/core/trace/content-assembler.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 var DEFAULT_BEFORE_CONTEXT = 5;
 var DEFAULT_AFTER_CONTEXT = 20;
 async function assembleContent(result, taskPath, contextOptions) {
@@ -4488,7 +4605,7 @@ async function cachedReadFile(cache, filePath) {
   if (cache.has(filePath)) return cache.get(filePath) ?? null;
   let content;
   try {
-    content = await readFile9(filePath, "utf-8");
+    content = await readFile10(filePath, "utf-8");
   } catch {
     content = null;
   }
@@ -4838,7 +4955,7 @@ function pushToMap(map, key, value) {
 }
 
 // src/core/trace/input-resolver.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 function resolveIds(ids, index) {
   const resolved = [];
   const warnings = [];
@@ -4854,7 +4971,7 @@ function resolveIds(ids, index) {
 async function resolveTaskFile(taskPath, index) {
   let content;
   try {
-    content = await readFile10(taskPath, "utf-8");
+    content = await readFile11(taskPath, "utf-8");
   } catch {
     return { ids: [], warnings: [`Task file not found: ${taskPath}`] };
   }
@@ -4905,7 +5022,7 @@ async function resolveTaskFile(taskPath, index) {
 async function resolveSourceFile(filePath, index) {
   let content;
   try {
-    content = await readFile10(filePath, "utf-8");
+    content = await readFile11(filePath, "utf-8");
   } catch {
     return { ids: [], warnings: [`Source file not found: ${filePath}`] };
   }
@@ -5378,15 +5495,15 @@ function printUpdateWarning(log, result) {
 }
 
 // src/utils/update-check-cache.ts
-import { mkdir as mkdir3, readFile as readFile11, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile12, writeFile as writeFile4 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname3, join as join13 } from "path";
-var CACHE_DIR = join13(homedir(), ".cache", "awa");
-var CACHE_FILE = join13(CACHE_DIR, "update-check.json");
+import { dirname as dirname3, join as join14 } from "path";
+var CACHE_DIR = join14(homedir(), ".cache", "awa");
+var CACHE_FILE = join14(CACHE_DIR, "update-check.json");
 var DEFAULT_INTERVAL_MS = 864e5;
 async function shouldCheck(intervalMs = DEFAULT_INTERVAL_MS) {
   try {
-    const raw = await readFile11(CACHE_FILE, "utf-8");
+    const raw = await readFile12(CACHE_FILE, "utf-8");
     const data = JSON.parse(raw);
     if (typeof data.timestamp !== "number" || typeof data.latestVersion !== "string") {
       return true;
@@ -5501,6 +5618,10 @@ program.command("check").description(
 ).option(
   "--no-fix",
   "Skip regeneration of Requirements Traceability sections in DESIGN and TASK files"
+).option(
+  "--deprecated",
+  "Surface warnings for code markers and cross-references targeting deprecated IDs",
+  false
 ).action(async (options, command) => {
   const cliOptions = {
     config: cliProvidedOption(command, options, "config"),
@@ -5511,7 +5632,8 @@ program.command("check").description(
     summary: cliProvidedOption(command, options, "summary"),
     allowWarnings: cliProvidedOption(command, options, "allowWarnings"),
     specOnly: cliProvidedOption(command, options, "specOnly"),
-    fix: cliProvidedOption(command, options, "fix")
+    fix: cliProvidedOption(command, options, "fix"),
+    deprecated: cliProvidedOption(command, options, "deprecated")
   };
   const exitCode = await checkCommand(cliOptions);
   process.exit(exitCode);
@@ -5632,7 +5754,7 @@ var isDisabledByEnv = !!process.env.NO_UPDATE_NOTIFIER;
 if (!isJsonOrSummary && isTTY && !isDisabledByEnv) {
   updateCheckPromise = (async () => {
     try {
-      const { configLoader: configLoader2 } = await import("./config-SJLBJX77.js");
+      const { configLoader: configLoader2 } = await import("./config-EP5JOR5X.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"];