deuk-agent-rule 2.5.13 → 3.3.2

package/scripts/cli-ticket-index.mjs

@@ -0,0 +1,298 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { hostname as osHostname } from "os";
+import { 
+  AGENT_ROOT_DIR, TICKET_SUBDIR, TICKET_INDEX_FILENAME,
+  toSlug, findFileRecursively, toRepoRelativePath, detectConsumerTicketDir, computeTicketPath, normalizeTicketGroup
+} from "./cli-utils.mjs";
+
+const TICKET_ARCHIVE_INDEX_FILENAME = "INDEX.archive.json";
+const TICKET_ARCHIVE_INDEX_PREFIX = "INDEX.archive.";
+const ARCHIVE_INDEX_RETENTION_MONTHS = 12;
+const ARCHIVE_INDEX_MONTH_RE = /^INDEX\.archive\.(\d{4}-\d{2})\.json$/;
+const ARCHIVE_INDEX_LEGACY_RE = /^INDEX\.archive\.json$/;
+
+function parseArchiveMonth(value) {
+  const match = String(value || "").match(/^(\d{4})-(\d{2})$/);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12) return null;
+  return { year, month, yearMonth: `${match[1]}-${match[2]}` };
+}
+
+function monthDistance(fromYearMonth, toDate = new Date()) {
+  const parsed = parseArchiveMonth(fromYearMonth);
+  if (!parsed) return null;
+  return (toDate.getUTCFullYear() * 12 + toDate.getUTCMonth()) - ((parsed.year * 12) + (parsed.month - 1));
+}
+
+function resolveArchivePartition(entry, now = new Date()) {
+  const fromEntry = parseArchiveMonth(entry?.archiveYearMonth);
+  if (fromEntry) {
+    return {
+      yearMonth: fromEntry.yearMonth,
+      day: String(entry.archiveDay || "").match(/^\d{2}$/)?.[0] || String(now.getUTCDate()).padStart(2, "0")
+    };
+  }
+
+  const source = String(entry?.createdAt || entry?.updatedAt || "");
+  const match = source.match(/^(\d{4})-(\d{2})-(\d{2})/);
+  if (match) {
+    return { yearMonth: `${match[1]}-${match[2]}`, day: match[3] };
+  }
+
+  return {
+    yearMonth: `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}`,
+    day: String(now.getUTCDate()).padStart(2, "0")
+  };
+}
+
+function shouldRetainArchiveEntry(entry, now = new Date()) {
+  const partition = resolveArchivePartition(entry, now);
+  const distance = monthDistance(partition.yearMonth, now);
+  if (distance === null) return true;
+  return distance <= ARCHIVE_INDEX_RETENTION_MONTHS;
+}
+
+function archiveIndexFilePath(dir, yearMonth = null) {
+  return join(dir, yearMonth ? `${TICKET_ARCHIVE_INDEX_PREFIX}${yearMonth}.json` : TICKET_ARCHIVE_INDEX_FILENAME);
+}
+
+function listArchiveIndexFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(ent => ent.isFile())
+    .map(ent => join(dir, ent.name))
+    .filter(abs => ARCHIVE_INDEX_LEGACY_RE.test(basename(abs)) || ARCHIVE_INDEX_MONTH_RE.test(basename(abs)))
+    .sort((a, b) => {
+      const aBase = basename(a);
+      const bBase = basename(b);
+      const aMatch = aBase.match(ARCHIVE_INDEX_MONTH_RE);
+      const bMatch = bBase.match(ARCHIVE_INDEX_MONTH_RE);
+      if (aMatch && !bMatch) return 1;
+      if (!aMatch && bMatch) return -1;
+      if (!aMatch && !bMatch) return aBase.localeCompare(bBase);
+      return aMatch[1].localeCompare(bMatch[1]);
+    });
+}
+
+function parseIndexFile(absPath) {
+  if (!existsSync(absPath)) {
+    return { version: 1, updatedAt: null, activeTicketId: null, entries: [] };
+  }
+  try {
+    const j = JSON.parse(readFileSync(absPath, "utf8"));
+    const entries = Array.isArray(j.entries) ? j.entries.map(e => {
+      const entry = { ...e, status: e.status || "open", group: normalizeTicketGroup(e.group, "sub") };
+      entry.path = computeTicketPath(entry);
+      return entry;
+    }) : [];
+    return {
+      version: j.version || 1,
+      updatedAt: j.updatedAt ?? null,
+      activeTicketId: j.activeTicketId ?? null,
+      entries
+    };
+  } catch (err) {
+    console.error(`[ERROR] Failed to parse ${basename(absPath)} at ${absPath}:`, err.message);
+    return { version: 1, updatedAt: null, activeTicketId: null, entries: [], _corrupt: true };
+  }
+}
+
+function splitEntriesForStorage(entries = []) {
+  const activeEntries = [];
+  const archiveEntries = [];
+  for (const entry of entries) {
+    const status = String(entry?.status || "open").toLowerCase();
+    if (status === "open" || status === "active") {
+      activeEntries.push(entry);
+    } else {
+      archiveEntries.push(entry);
+    }
+  }
+  return { activeEntries, archiveEntries };
+}
+
+function partitionArchiveEntries(entries = []) {
+  const retained = [];
+  const retired = [];
+  for (const entry of entries) {
+    if (shouldRetainArchiveEntry(entry)) retained.push(entry);
+    else retired.push(entry);
+  }
+  return { retained, retired };
+}
+
+function mergeIndexEntries(primaryEntries = [], archiveEntries = []) {
+  const merged = new Map();
+  for (const entry of primaryEntries || []) {
+    if (entry?.id) merged.set(entry.id, entry);
+  }
+  for (const entry of archiveEntries || []) {
+    if (entry?.id) merged.set(entry.id, entry);
+  }
+  return Array.from(merged.values());
+}
+
+export function readTicketIndexJson(cwd) {
+  const dir = detectConsumerTicketDir(cwd);
+  if (!dir) return { version: 1, updatedAt: null, entries: [] };
+  const mainPath = join(dir, TICKET_INDEX_FILENAME);
+  const main = parseIndexFile(mainPath);
+  const archiveFiles = listArchiveIndexFiles(dir).map(parseIndexFile);
+
+  const archiveEntries = archiveFiles.flatMap(file => file.entries || []);
+  const entries = mergeIndexEntries(main.entries, archiveEntries).map(entry => {
+    const next = { ...entry, status: entry.status || "open", group: normalizeTicketGroup(entry.group, "sub") };
+    next.path = computeTicketPath(next);
+    return next;
+  });
+
+  return {
+    version: main.version || archiveFiles[0]?.version || 1,
+    updatedAt: main.updatedAt ?? archiveFiles[0]?.updatedAt ?? null,
+    activeTicketId: main.activeTicketId ?? null,
+    entries,
+    _corrupt: Boolean(main._corrupt || archiveFiles.some(file => file._corrupt))
+  };
+}
+
+export function writeTicketIndexJson(cwd, indexJson, opts = {}) {
+  if (indexJson._corrupt && !opts.force) {
+    console.error(`[ABORT] Refusing to overwrite potentially corrupt ${TICKET_INDEX_FILENAME}. Use --force to override.`);
+    return;
+  }
+  const dir = detectConsumerTicketDir(cwd, { createIfMissing: true });
+  const p = join(dir, TICKET_INDEX_FILENAME);
+  if (opts.dryRun) return;
+  mkdirSync(dir, { recursive: true });
+  
+  const out = { ...indexJson };
+  delete out._corrupt;
+  
+  // Strip physical path snapshots before saving to enforce state-driven resolution
+  const entries = Array.isArray(out.entries) ? out.entries : [];
+  const { activeEntries, archiveEntries } = splitEntriesForStorage(entries);
+  out.entries = activeEntries.map(e => {
+    const { path, ...clean } = e;
+    return clean;
+  });
+  out.activeTicketId = out.activeTicketId || activeEntries.find(e => e.status === "active")?.id || activeEntries.find(e => e.status === "open")?.id || null;
+  writeFileSync(p, JSON.stringify(out, null, 2) + "\n", "utf8");
+
+  const archiveFiles = listArchiveIndexFiles(dir);
+  const retainedArchiveEntries = partitionArchiveEntries(archiveEntries);
+  const archiveBuckets = new Map();
+
+  for (const entry of retainedArchiveEntries.retained) {
+    const partition = resolveArchivePartition(entry);
+    const bucket = archiveBuckets.get(partition.yearMonth) || [];
+    bucket.push({ ...entry, archiveYearMonth: partition.yearMonth, archiveDay: partition.day });
+    archiveBuckets.set(partition.yearMonth, bucket);
+  }
+
+  const desiredArchiveFiles = new Set();
+  for (const [yearMonth, bucket] of archiveBuckets.entries()) {
+    const archiveOut = {
+      version: out.version || 1,
+      updatedAt: out.updatedAt || new Date().toISOString(),
+      activeTicketId: null,
+      entries: bucket.map(e => {
+        const { path, ...clean } = e;
+        return clean;
+      })
+    };
+    const archivePath = archiveIndexFilePath(dir, yearMonth);
+    desiredArchiveFiles.add(archivePath);
+    writeFileSync(archivePath, JSON.stringify(archiveOut, null, 2) + "\n", "utf8");
+  }
+
+  for (const filePath of archiveFiles) {
+    if (!desiredArchiveFiles.has(filePath)) {
+      unlinkSync(filePath);
+    }
+  }
+
+  if (retainedArchiveEntries.retired.length > 0) {
+    console.log(`[GC] Dropped ${retainedArchiveEntries.retired.length} archived entries outside the ${ARCHIVE_INDEX_RETENTION_MONTHS}-month retention window.`);
+  }
+}
+
+export function getHostnameSlug() {
+  try {
+    const slug = osHostname().toLowerCase().replace(/[^a-z0-9\-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    return slug.slice(0, 8).replace(/-$/, '') || 'local';
+  } catch {
+    return 'local';
+  }
+}
+
+export function computeNextTicketNumber(existingEntries) {
+  const hostname = getHostnameSlug();
+  const newRe = /^(\d{3,4})-/;
+  let max = 0;
+  for (const e of (existingEntries || [])) {
+    const id = String(e.id || '');
+    const m = id.match(newRe);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max && n < 10000) max = n;
+    }
+  }
+  return { num: max + 1, hostname };
+}
+
+export function generateTicketId(topicSlug, existingEntries) {
+  const hostname = getHostnameSlug();
+  const slug = toSlug(topicSlug || 'ticket');
+  const match = slug.match(/^(\d{3,4})-(.*)/);
+  if (match) {
+    const numStr = match[1];
+    const restSlug = match[2].slice(0, 32);
+    return `${numStr}-${restSlug}-${hostname}`;
+  }
+  const { num } = computeNextTicketNumber(existingEntries);
+  const numStr = String(num).padStart(3, '0');
+  const finalSlug = slug.slice(0, 32);
+  return `${numStr}-${finalSlug}-${hostname}`;
+}
+
+export function syncActiveTicketId(cwd, opts = {}) {
+  const index = readTicketIndexJson(cwd);
+  const activeEntry = index.entries.find(e => e.status === "active") || 
+                       index.entries.find(e => e.status === "open");
+  
+  const ticketDir = detectConsumerTicketDir(cwd);
+  if (!ticketDir) return;
+  if (opts.dryRun) return;
+
+  const activeId = activeEntry ? activeEntry.id : null;
+  if (index.activeTicketId !== activeId) {
+      writeTicketIndexJson(cwd, { ...index, activeTicketId: activeId });
+  }
+
+  const legacyLatestPath = join(ticketDir, "LATEST.md");
+  const pointerPathMd = join(ticketDir, "ACTIVE_TICKET.md");
+  const pointerPathJson = join(ticketDir, "ACTIVE_TICKET.json");
+  
+  for (const p of [legacyLatestPath, pointerPathMd, pointerPathJson]) {
+    if (existsSync(p)) {
+      unlinkSync(p);
+    }
+  }
+}
+
+export async function syncToPipeline(url, data) {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(data),
+      signal: AbortSignal?.timeout ? AbortSignal.timeout(3000) : undefined
+    });
+    return response.ok;
+  } catch (err) {
+    return false;
+  }
+}

package/scripts/cli-ticket-migration.mjs

@@ -0,0 +1,320 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync, statSync } from "fs";
+import { basename, dirname, join, relative } from "path";
+import {
+  toRepoRelativePath, AGENT_ROOT_DIR, TICKET_SUBDIR, TICKET_LIST_FILENAME,
+  parseFrontMatter, stringifyFrontMatter, findFileRecursively, detectConsumerTicketDir
+} from "./cli-utils.mjs";
+import { readTicketIndexJson, writeTicketIndexJson, syncActiveTicketId } from "./cli-ticket-index.mjs";
+import { collectTicketMarkdownFiles, rebuildTicketIndexFromTopicFilesIfNeeded } from "./cli-ticket-parser.mjs";
+
+// ─── Summary Extraction ─────────────────────────────────────────────────────
+
+/**
+ * Extracts a concise summary from ticket body content for legacy tickets.
+ * Strategy: combine title + scope/background + top tasks into 1-2 lines.
+ * Handles 3 legacy formats:
+ *   - Old format: 🎯 Scope Bounds, 📁 Files to Modify
+ *   - Mid format: ## Background, ## Analysis, ## Tasks
+ *   - New format: ## Target Module, ## APC (already has summary usually)
+ */
+export function extractSummary(meta, content) {
+  const title = meta.title || "";
+  const lines = content.split("\n");
+
+  // Collect section contents by known header patterns
+  const sections = {};
+  let currentSection = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Match ## headers (with or without emoji prefix)
+    const headerMatch = trimmed.match(/^##\s+(?:[\u{1F3AF}\u{1F4C1}\u{1F3D7}\u{1F6D1}\u{1F504}\u{2705}\s]*)?(.+)$/u);
+    if (headerMatch) {
+      currentSection = headerMatch[1].trim().toLowerCase();
+      sections[currentSection] = [];
+      continue;
+    }
+    // Match # title
+    if (trimmed.startsWith("# ") && !currentSection) {
+      continue; // skip title line
+    }
+    if (currentSection && trimmed && !trimmed.startsWith(">") && !trimmed.startsWith("<!--")) {
+      sections[currentSection].push(trimmed);
+    }
+  }
+
+  // Priority: scope/background > analysis > tasks
+  let contextLine = "";
+
+  // Try scope bounds (old format)
+  const scopeKeys = Object.keys(sections).filter(k =>
+    k.includes("scope") || k.includes("target") || k.includes("background")
+  );
+  for (const key of scopeKeys) {
+    const scopeLines = (sections[key] || [])
+      .filter(l => !l.startsWith("- **Context") && !l.startsWith("["))
+      .map(l => l.replace(/^[-*]\s*\*\*[^*]+:\*\*\s*/, "").replace(/`/g, ""))
+      .filter(l => l.length > 5 && l.length < 200);
+    if (scopeLines.length > 0) {
+      contextLine = scopeLines[0];
+      break;
+    }
+  }
+
+  // Try analysis section if no scope found
+  if (!contextLine) {
+    const analysisKeys = Object.keys(sections).filter(k =>
+      k.includes("analysis") || k.includes("design") || k.includes("decisions")
+    );
+    for (const key of analysisKeys) {
+      const analysisLines = (sections[key] || [])
+        .filter(l => l.length > 10 && l.length < 200 && !l.startsWith("|"))
+        .map(l => l.replace(/^[-*]\s*/, ""));
+      if (analysisLines.length > 0) {
+        contextLine = analysisLines[0];
+        break;
+      }
+    }
+  }
+
+  // Collect task summary (first 3 task items)
+  const taskKeys = Object.keys(sections).filter(k =>
+    k.includes("task") || k.includes("phased") || k.includes("execution steps")
+  );
+  let taskItems = [];
+  for (const key of taskKeys) {
+    taskItems = (sections[key] || [])
+      .filter(l => /^-\s*\[[ x]\]/.test(l) || /^\d+\.\s*\[/.test(l))
+      .map(l => l.replace(/^[-*\d.]+\s*\[[ x]\]\s*/, "").replace(/\[Phase\s*\d+[>]\s*/i, "").replace(/]/g, "").trim())
+      .filter(l => l.length > 3)
+      .slice(0, 3);
+    if (taskItems.length > 0) break;
+  }
+
+  // Build summary
+  const parts = [];
+  if (contextLine) {
+    parts.push(contextLine.length > 120 ? contextLine.substring(0, 117) + "..." : contextLine);
+  }
+  if (taskItems.length > 0) {
+    parts.push(`주요 작업: ${taskItems.join(", ")}`);
+  }
+
+  if (parts.length === 0) {
+    // Fallback: use title itself as summary
+    return title || null;
+  }
+
+  const summary = parts.join(". ").substring(0, 300);
+  return summary || null;
+}
+
+// ─── CAUTION Block / Target Module Injection ─────────────────────────────────
+
+const CAUTION_BLOCK = `> **[CAUTION FOR AI AGENTS]**
+> 1. Restrict all analysis, file creation, and modifications to the declared **Target Module** below.
+> 2. Read the files listed in **Context Files** before doing ANY code generation.
+> 3. DO NOT leak configuration, logic, or dependencies from other modules.
+
+## Target Module
+- **Target:** [Fill in the target module/submodule path]
+- **Context Files:** [List architecture docs or key files to read first]`;
+
+/**
+ * Ensures the CAUTION block and Target Module section exist after the title.
+ * Returns modified content or null if no change needed.
+ */
+export function ensureCautionBlock(content) {
+  // Already has Target Module or the new-format CAUTION
+  if (content.includes("## Target Module")) return null;
+
+  // Also skip if it already has the old-format scope bounds (don't duplicate)
+  const hasOldScope = /## [\u{1F3AF}]?\s*Scope Bounds/u.test(content);
+  if (hasOldScope) return null;
+
+  // Find the # title line and insert after it
+  const titleMatch = content.match(/^(# .+)\n/m);
+  if (!titleMatch) return null;
+
+  const titleEnd = content.indexOf(titleMatch[0]) + titleMatch[0].length;
+  const before = content.substring(0, titleEnd);
+  let after = content.substring(titleEnd);
+
+  // Skip if CAUTION already exists (old variant)
+  if (after.includes("[CAUTION FOR AI AGENTS]")) return null;
+
+  return before + "\n" + CAUTION_BLOCK + "\n" + after;
+}
+
+// ─── Main Migration ─────────────────────────────────────────────────────────
+
+export function performUpgradeMigration(cwd, opts = {}) {
+  const root = detectConsumerTicketDir(cwd, { createIfMissing: true });
+  
+  const files = collectTicketMarkdownFiles(root).filter(p => {
+    const base = basename(p);
+    return base !== "LATEST.md" && base !== TICKET_LIST_FILENAME && base !== "ACTIVE_TICKET.md";
+  });
+
+  console.log(`[UPGRADE] Scanning ${files.length} tickets for V2 migration...`);
+
+  let upgraded = 0;
+  let summaryAdded = 0;
+  let cautionAdded = 0;
+
+  for (const abs of files) {
+    const rel = toRepoRelativePath(cwd, abs);
+    const body = readFileSync(abs, "utf8");
+    const { meta, content } = parseFrontMatter(body);
+    let dirty = false;
+    let modifiedContent = content;
+
+    const isAlreadyInArchive = rel.includes("/archive/");
+
+    // 1. Summary enrichment for legacy tickets
+    if (!meta.summary) {
+      const generated = extractSummary(meta, content);
+      if (generated) {
+        meta.summary = generated;
+        dirty = true;
+        summaryAdded++;
+      }
+    }
+
+    // 2. CAUTION / Target Module injection
+    const cautionResult = ensureCautionBlock(modifiedContent);
+    if (cautionResult !== null) {
+      modifiedContent = cautionResult;
+      dirty = true;
+      cautionAdded++;
+    }
+
+    // 3. Archive placement fix (existing logic)
+    if (meta.status === "archived" && !isAlreadyInArchive && !opts.dryRun) {
+      const finalAbs = moveFileToArchive(cwd, abs, meta.group || basename(dirname(abs)));
+      const migratedBody = stringifyFrontMatter(meta, modifiedContent);
+      writeFileSync(finalAbs, migratedBody, "utf8");
+      upgraded++;
+      console.log(`[OK] Upgraded + archived: ${toRepoRelativePath(cwd, finalAbs)}`);
+      continue;
+    }
+
+    if (dirty) {
+      if (opts.dryRun) {
+        const changes = [];
+        if (!parseFrontMatter(body).meta.summary && meta.summary) changes.push("summary");
+        if (cautionResult !== null) changes.push("caution+targetModule");
+        console.log(`[DRY-RUN] Would upgrade: ${rel} (+${changes.join(", ")})`);
+      } else {
+        const migratedBody = stringifyFrontMatter(meta, modifiedContent);
+        writeFileSync(abs, migratedBody, "utf8");
+        upgraded++;
+      }
+    }
+  }
+
+  console.log(`[UPGRADE] Results: ${upgraded} upgraded, ${summaryAdded} summaries added, ${cautionAdded} caution blocks added`);
+
+  if (!opts.dryRun) {
+    rebuildTicketIndexFromTopicFilesIfNeeded(cwd, { ...opts, force: true });
+    performDefragmentation(cwd, opts);
+    syncActiveTicketId(cwd);
+  }
+  
+  return upgraded;
+}
+
+// ─── Defragmentation ────────────────────────────────────────────────────────
+
+export function performDefragmentation(cwd, opts = {}) {
+  const rootTicketDir = detectConsumerTicketDir(cwd);
+  if (!rootTicketDir) return;
+  const tickets = collectTicketMarkdownFiles(rootTicketDir).filter(p => {
+    const base = basename(p);
+    return base !== "LATEST.md" && base !== TICKET_LIST_FILENAME && base !== "ACTIVE_TICKET.md";
+  });
+
+  console.log(`[DEFRAG] Checking ${tickets.length} tickets for workspace placement...`);
+
+  const modifiedPaths = new Set();
+  
+  for (const abs of tickets) {
+    const { meta } = parseFrontMatter(readFileSync(abs, "utf8"));
+    if (meta.submodule && meta.submodule !== "global") {
+      const subPath = join(cwd, meta.submodule);
+      if (existsSync(subPath) && statSync(subPath).isDirectory()) {
+        const subTicketDir = join(subPath, AGENT_ROOT_DIR, TICKET_SUBDIR);
+        
+        const relToRoot = relative(rootTicketDir, abs);
+        const destAbs = join(subTicketDir, relToRoot);
+        
+        if (opts.dryRun) {
+          console.log(`[DRY-RUN] Would move to workspace: ${relToRoot} -> ${meta.submodule}/${AGENT_ROOT_DIR}/${TICKET_SUBDIR}/`);
+        } else {
+          mkdirSync(dirname(destAbs), { recursive: true });
+          copyFileSync(abs, destAbs);
+          unlinkSync(abs);
+          console.log(`[DEFRAG] Moved: ${meta.submodule}/${AGENT_ROOT_DIR}/${TICKET_SUBDIR}/${relToRoot}`);
+          modifiedPaths.add(subPath);
+        }
+      }
+    }
+  }
+
+  if (!opts.dryRun) {
+    for (const p of modifiedPaths) {
+      rebuildTicketIndexFromTopicFilesIfNeeded(p, { ...opts, force: true });
+      syncActiveTicketId(p);
+    }
+  }
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────
+
+export function moveFileToArchive(cwd, abs, group) {
+  const ticketDir = detectConsumerTicketDir(cwd);
+  const archiveBase = join(ticketDir, "archive");
+  const targetSubDir = (basename(ticketDir) === TICKET_SUBDIR || !group) ? "sub" : group;
+  const targetDir = join(archiveBase, targetSubDir);
+  mkdirSync(targetDir, { recursive: true });
+  const finalAbs = join(targetDir, basename(abs));
+  if (finalAbs !== abs) {
+    if (existsSync(finalAbs)) {
+      unlinkSync(abs);
+    } else {
+      writeFileSync(finalAbs, readFileSync(abs, "utf8"), "utf8");
+      unlinkSync(abs);
+    }
+  }
+  return finalAbs;
+}
+
+export function normalizeTicketPaths(cwd, opts = {}) {
+  const index = readTicketIndexJson(cwd);
+  const ticketDir = detectConsumerTicketDir(cwd);
+  const entries = index.entries || [];
+  let modified = false;
+
+  for (const entry of entries) {
+    if (!entry.path) continue;
+    
+    const currentAbs = join(cwd, entry.path);
+    if (!existsSync(currentAbs)) {
+      const fileName = basename(entry.path);
+      const found = findFileRecursively(ticketDir, fileName);
+      if (found) {
+        const newRel = toRepoRelativePath(cwd, found);
+        if (entry.path !== newRel) {
+          entry.path = newRel;
+          modified = true;
+        }
+      }
+    }
+  }
+
+  if (modified) {
+    index.updatedAt = new Date().toISOString();
+    writeTicketIndexJson(cwd, index);
+    if (!opts.silent) console.log(`[NORMALIZE] Corrected stale paths in ${basename(cwd)}/INDEX.json`);
+  }
+  return modified;
+}