deuk-agent-flow 4.0.37 → 4.2.7

package/scripts/cli-ticket-commands.mjs

@@ -1,12 +1,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync, readdirSync, rmSync, statSync } from "fs";
 import { hostname } from "os";
 import { basename, join, dirname, relative, resolve } from "path";
-import { 
+import {
   toSlug, toSnakeCaseKey, requireNonEmptySlug, toRepoRelativePath, toFileUri, inferRefTitleAndTopic, resolveReferencedTicketPath, toPosixPath, stringifyFrontMatter,
   resolveDocsLanguage, inferDocsLanguageFromText, normalizeDocsLanguage, isMcpActive, withReadline, parseFrontMatter,
   AGENT_ROOT_DIR, TICKET_SUBDIR, TICKET_DIR_NAME, TICKET_INDEX_FILENAME, WORKFLOW_MODE_EXECUTE,
   detectConsumerTicketDir, resolveConsumerTicketRoot, loadInitConfig, computeTicketPath, normalizeWorkflowMode
 } from "./cli-utils.mjs";
+import {
+  readTicketDocument,
+  resolveTicketEntryOrComputedPath,
+  resolveTicketKnowledgeDir,
+  resolveTicketReportDir
+} from "./cli-ticket-command-shared.mjs";
 import { readTicketIndexJson, writeTicketIndexJson, syncActiveTicketId, generateTicketId, syncToPipeline } from "./cli-ticket-index.mjs";
 import { appendTicketEntry, rebuildTicketIndexFromTopicFilesIfNeeded, updateTicketEntryStatus } from "./cli-ticket-parser.mjs";
 import { appendInternalWorkflowEvent, buildTelemetrySummary, getTelemetryCompactSummary } from "./cli-telemetry-commands.mjs";
@@ -250,25 +256,30 @@ function hasSubstantiveSectionContent(text, scaffolds = []) {
   return !scaffolds.some(phrase => normalized.includes(phrase));
 }
 
-function getMarkerBody(text, marker, nextMarkers) {
-  const lines = String(text || "").split("\n");
-  const start = lines.findIndex(line => line.includes(marker));
-  if (start < 0) return null;
+function hasApcMarker(text, marker) {
+  const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const markerPattern = new RegExp(`^\\s*(?:#{1,6}\\s+)?${escapedMarker}(?:\\s|$)`);
+  return String(text || "").split("\n").some(line => markerPattern.test(line));
+}
 
-  const body = [];
-  for (const line of lines.slice(start + 1)) {
-    if (nextMarkers.some(nextMarker => line.includes(nextMarker))) break;
-    body.push(line);
-  }
-  return body.join("\n").trim();
+function getApcContentWithoutMarkers(text) {
+  return String(text || "")
+    .split("\n")
+    .map(line => {
+      for (const { marker } of REQUIRED_APC_MARKERS) {
+        const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const markerPattern = new RegExp(`^\\s*(?:#{1,6}\\s+)?${escapedMarker}\\s*`);
+        if (markerPattern.test(line)) return line.replace(markerPattern, "");
+      }
+      return line;
+    })
+    .join("\n")
+    .trim();
 }
 
 function getMissingApcFields(text) {
   return REQUIRED_APC_MARKERS
-    .filter(({ marker }, index) => {
-      const nextMarkers = REQUIRED_APC_MARKERS.slice(index + 1).map(item => item.marker);
-      return !hasSubstantiveSectionContent(getMarkerBody(text, marker, nextMarkers), []);
-    })
+    .filter(({ marker }) => !hasApcMarker(text, marker))
     .map(field => field.name);
 }
 
@@ -288,6 +299,9 @@ function getPhase1PlanBodyReasons(body) {
     for (const field of getMissingApcFields(apcSection)) {
       reasons.push(`apc_${field}_missing`);
     }
+    if (!hasSubstantiveSectionContent(getApcContentWithoutMarkers(apcSection), [])) {
+      reasons.push("apc_content_incomplete");
+    }
   }
 
   for (const sectionName of REQUIRED_PHASE1_DATA_SECTIONS) {
@@ -312,7 +326,7 @@ function buildPlanBodyRequiredMessage(reasons = []) {
     "Use the AGENTS.md self-serve recipe: do not ask the user, call help, or search for templates.",
     "Run with stdin: `deuk-agent-flow ticket create --topic <topic> --summary \"<summary>\" --plan-body-file - --non-interactive`.",
     "Use these exact H2 headings: `## Agent Permission Contract (APC)`, `## Compact Plan`, `## Problem Analysis`, `## Source Observations`, `## Cause Hypotheses`, `## Improvement Direction`, `## Audit Evidence`.",
-    "Under `## Agent Permission Contract (APC)`, include `[BOUNDARY]`, `[CONTRACT]`, and `[PATCH PLAN]`.",
+    "Under `## Agent Permission Contract (APC)`, use `### [BOUNDARY]`, `### [CONTRACT]`, and `### [PATCH PLAN]`; write each body on following lines.",
     "If a scratch plan-body file is unavoidable, keep it outside the workspace, delete it after create, and never present it as a ticket artifact.",
     "Do not rely on template defaults or auto-generated filler text for Phase 1 ticket content."
   ].join("\n");
@@ -757,8 +771,13 @@ function rollbackTicketLifecycleArtifacts(cwd, previousIndex, previousBody, absP
 }
 
 function getPhase1IncompleteReasonsFromBody(body) {
-  parseFrontMatter(body);
-  return [];
+  let parsed = { meta: {}, content: "" };
+  try {
+    parsed = parseFrontMatter(body);
+  } catch (err) {
+    return ["frontmatter_parse_failed"];
+  }
+  return getPhase1PlanBodyReasons(normalizePhase1PlanBodyHeadings(parsed.content || ""));
 }
 
 function getPhase1IncompleteReasons(cwd, absPath) {
@@ -981,18 +1000,53 @@ function buildOpenTicketLimitError(indexJson) {
   return lines.join("\n");
 }
 
+function topicKeysForEntry(entry = {}) {
+  const keys = [entry.topic, entry.id];
+  try {
+    if (entry.title) keys.push(toSlug(entry.title));
+  } catch {
+    // Non-ASCII or otherwise unsluggable titles are not duplicate keys.
+  }
+  return keys
+    .map(value => String(value || "").toLowerCase())
+    .filter(Boolean);
+}
+
+function findReusableCompletedTicket(indexJson, topic, opts = {}) {
+  const key = String(topic || "").toLowerCase();
+  if (!key) return null;
+  return filterTicketEntries(indexJson.entries, opts)
+    .filter(entry => !OPEN_TICKET_STATUSES.has(String(entry.status || "open").toLowerCase()))
+    .sort((a, b) => String(b.updatedAt || b.createdAt || "").localeCompare(String(a.updatedAt || a.createdAt || "")))
+    .find(entry => topicKeysForEntry(entry).includes(key)) || null;
+}
+
+function buildReusableTicketCreateError(entry, topic) {
+  const id = entry?.id || entry?.topic || topic;
+  const status = entry?.status || "closed";
+  return [
+    `[DUPLICATE TICKET BLOCKED] A ${status} ticket already matches "${topic}".`,
+    `Existing ticket: ${id}`,
+    "Do not guess .deuk-agent/tickets/sub paths for closed or archived tickets.",
+    `Use: deuk-agent-flow ticket status --topic ${id} --status-detail --non-interactive`,
+    `Or:  deuk-agent-flow ticket use --topic ${id} --non-interactive`,
+    "Create a new ticket only when the scope is genuinely different; use a distinct topic for that scope."
+  ].join("\n");
+}
+
 function resolveArchiveReport(cwd, fileName, report) {
   if (report) return resolve(cwd, report);
 
-  const reportDir = join(cwd, AGENT_ROOT_DIR, "docs", "plan");
+  const reportDir = resolveTicketReportDir(cwd);
   const potentialReport = fileName.replace(/\.md$/i, "-report.md");
   const potentialPath = join(reportDir, potentialReport);
   return existsSync(potentialPath) ? potentialPath : null;
 }
 
 function archiveTicketEntry({ cwd, ticketDir, indexJson, found, opts = {}, report }) {
-  const absPath = join(cwd, found.path);
-  const fileName = found.path.split(/[/\\]/).pop();
+  const absPath = resolveTicketEntryOrComputedPath(cwd, found);
+  const fileName = (found.path || computeTicketPath(found)).split(/[/\\]/).pop();
+  const resolvedRelPath = found.path || computeTicketPath(found);
   if (!existsSync(absPath)) {
     const archivedAbsPath = findExistingArchivedTicketPath(ticketDir, found, fileName);
     if (archivedAbsPath) {
@@ -1027,7 +1081,7 @@ function archiveTicketEntry({ cwd, ticketDir, indexJson, found, opts = {}, repor
       }
       return { id: found.id, path: archivedRelativePath, normalized: true };
     }
-    throw new Error("ticket archive: file not found " + found.path);
+    throw new Error("ticket archive: file not found " + resolvedRelPath);
   }
 
   const originalBody = readFileSync(absPath, "utf8");
@@ -1039,11 +1093,11 @@ function archiveTicketEntry({ cwd, ticketDir, indexJson, found, opts = {}, repor
   const reportSrc = resolveArchiveReport(cwd, fileName, report);
   let reportDest = null;
 
-    if (reportSrc) {
-      if (!existsSync(reportSrc)) {
-        throw new Error("ticket archive: report file not found " + report);
-      }
-      const reportDir = join(cwd, AGENT_ROOT_DIR, "docs", "plan");
+  if (reportSrc) {
+    if (!existsSync(reportSrc)) {
+      throw new Error("ticket archive: report file not found " + report);
+    }
+    const reportDir = resolveTicketReportDir(cwd);
     if (!opts.dryRun) mkdirSync(reportDir, { recursive: true });
 
     const reportBaseName = fileName.replace(/\.md$/i, "-report.md");
@@ -1213,20 +1267,25 @@ export async function runTicketCreate(opts) {
     }
 
     const indexJson = readTicketIndexJson(opts.cwd);
+    const reusableTicket = findReusableCompletedTicket(indexJson, finalTopic, opts);
+    if (reusableTicket) {
+      throw new Error(buildReusableTicketCreateError(reusableTicket, finalTopic));
+    }
 
     // Smart close: check previous active ticket's completion state before deciding
     const activeId = indexJson.activeTicketId;
     if (activeId) {
       const activeEntry = indexJson.entries.find(e => e.id === activeId && (e.status === "open" || e.status === "active"));
       if (activeEntry) {
-        const absPath = join(opts.cwd, activeEntry.path);
+        const activeDoc = readTicketDocument(opts.cwd, activeEntry, { action: "ticket create", requireExists: false });
+        const absPath = activeDoc.absPath;
         let shouldClose = false;
         let reason = "";
 
-        if (existsSync(absPath)) {
+        if (activeDoc.exists) {
           try {
-            const body = readFileSync(absPath, "utf8");
-            const { meta, content } = parseFrontMatter(body);
+            const body = activeDoc.body;
+            const { meta, content } = activeDoc;
 
             // Count checklist items
             const checked = (content.match(/- \[x\]/gi) || []).length;
@@ -1283,7 +1342,7 @@ export async function runTicketCreate(opts) {
 
 
 
-    const ticketId = generateTicketId(finalTopic, indexJson.entries);
+    const ticketId = generateTicketId(finalTopic, indexJson);
     const finalFileName = `${ticketId}.md`;
 
     const abs = join(ticketDir, group, finalFileName);
@@ -1480,11 +1539,10 @@ export async function runTicketStatus(opts) {
   const found = pickTicketEntry(opts, index);
   if (!found) throw new Error("ticket status: no matching ticket found");
 
-  const absPath = join(opts.cwd, found.path);
-  const fileMissing = !existsSync(absPath);
-  const body = fileMissing ? "" : readFileSync(absPath, "utf8");
-  const parsed = fileMissing ? { meta: {}, content: "" } : parseFrontMatter(body);
-  if (!fileMissing) assertTicketLifecycleProvenance(found, parsed.meta);
+  const ticketDoc = readTicketDocument(opts.cwd, found, { action: "ticket status", requireExists: false });
+  const absPath = ticketDoc.absPath;
+  const parsed = { meta: ticketDoc.meta, content: ticketDoc.content };
+  if (ticketDoc.exists) assertTicketLifecycleProvenance(found, parsed.meta);
   const phase = Number(parsed.meta.phase || 1);
   const incompleteReasons = getPhase1IncompleteReasons(opts.cwd, absPath);
   const derivedStatus = incompleteReasons.length > 0 && phase === 1
@@ -1494,7 +1552,7 @@ export async function runTicketStatus(opts) {
   const out = {
     id: found.id,
     title: found.title,
-    path: found.path,
+    path: toRepoRelativePath(opts.cwd, ticketDoc.absPath),
     phase,
     status: derivedStatus,
     summary: parsed.meta.summary || null,
@@ -1538,16 +1596,15 @@ export async function runTicketGuard(opts) {
     throw new Error("ticket guard: no matching durable ticket found; do not call set_workflow_context.");
   }
 
-  const absPath = join(opts.cwd, found.path);
-  if (!existsSync(absPath)) {
+  const ticketDoc = readTicketDocument(opts.cwd, found, { action: "ticket guard", requireExists: false });
+  if (!ticketDoc.exists) {
     throw new Error(`ticket guard: durable ticket file missing for ${found.id || found.topic}; do not call set_workflow_context.`);
   }
+  const { meta: parsedMeta } = ticketDoc;
+  const absPath = ticketDoc.absPath;
+  assertTicketLifecycleProvenance(found, parsedMeta);
 
-  const body = readFileSync(absPath, "utf8");
-  const parsed = parseFrontMatter(body);
-  assertTicketLifecycleProvenance(found, parsed.meta);
-
-  const phase = Number(parsed.meta.phase || 1);
+  const phase = Number(parsedMeta.phase || 1);
   const reasons = getPhase1IncompleteReasons(opts.cwd, absPath);
   if (phase === 1 && reasons.length > 0) {
     throw new Error(`[VALIDATION FAILED] ticket guard rejected incomplete Phase 1 for ${found.id || found.topic}: ${reasons.join(", ")}. Do not call set_workflow_context until the durable ticket is complete.`);
@@ -1566,8 +1623,8 @@ export async function runTicketGuard(opts) {
     id: found.id,
     topic: found.topic,
     phase,
-    status: parsed.meta.status || found.status || "open",
-    path: found.path
+    status: parsedMeta.status || found.status || "open",
+    path: toRepoRelativePath(opts.cwd, absPath)
   };
 
   if (opts.json) {
@@ -1585,10 +1642,10 @@ export async function runTicketHandoff(opts) {
   const current = pickTicketEntry(opts, index);
   if (!current) throw new Error("ticket handoff: no matching ticket found");
 
-  const currentAbs = join(opts.cwd, current.path);
-  const currentMissing = !existsSync(currentAbs);
-  const currentBody = currentMissing ? "" : readFileSync(currentAbs, "utf8");
-  const currentParsed = currentMissing ? { meta: {}, content: "" } : parseFrontMatter(currentBody);
+  const currentDoc = readTicketDocument(opts.cwd, current, { action: "ticket handoff", requireExists: false });
+  const currentAbs = currentDoc.absPath;
+  const currentMissing = !currentDoc.exists;
+  const currentParsed = currentMissing ? { meta: {}, content: "" } : { meta: currentDoc.meta, content: currentDoc.content };
   const currentPhase = Number(currentParsed.meta.phase || 1);
   const currentReasons = currentMissing ? ["ticket_file_missing"] : getPhase1IncompleteReasons(opts.cwd, currentAbs);
   const currentStatus = currentReasons.length > 0 && currentPhase === 1
@@ -1686,9 +1743,7 @@ export async function runTicketEvidenceCheck(opts) {
     throw new Error("ticket evidence: no matching ticket found.");
   }
 
-  const absPath = join(opts.cwd, target.path);
-  if (!existsSync(absPath)) throw new Error("Ticket file not found: " + target.path);
-  const { meta, content } = parseFrontMatter(readFileSync(absPath, "utf8"));
+  const { absPath, meta, content } = readTicketDocument(opts.cwd, target, { action: "ticket evidence", requireExists: true });
   const result = getClaimEvidenceResult(target, meta, content, opts.claim);
   const implementationGuard = getImplementationClaimGuardResult(opts.cwd, { claim: opts.claim, content, changedFiles: opts.changedFiles });
 
@@ -1717,9 +1772,7 @@ export async function runTicketEvidenceReport(opts) {
     throw new Error("ticket report: no matching ticket found.");
   }
 
-  const absPath = join(opts.cwd, target.path);
-  if (!existsSync(absPath)) throw new Error("Ticket file not found: " + target.path);
-  const { meta, content } = parseFrontMatter(readFileSync(absPath, "utf8"));
+  const { absPath, meta, content } = readTicketDocument(opts.cwd, target, { action: "ticket report", requireExists: true });
   const result = getClaimEvidenceResult(target, meta, content, opts.claim);
   const implementationGuard = getImplementationClaimGuardResult(opts.cwd, { claim: opts.claim, content, changedFiles: opts.changedFiles });
 
@@ -1772,10 +1825,8 @@ export async function runTicketClose(opts) {
     throw new Error("No matching ticket found to update status");
   }
 
-  const abs = join(opts.cwd, targetEntry.path);
-  if (!existsSync(abs)) throw new Error("Ticket file not found: " + targetEntry.path);
-  const previousBody = readFileSync(abs, "utf8");
-  const parsedForClose = parseFrontMatter(previousBody);
+  const { absPath: abs, meta: closeMeta, body: previousBody, content: closeContent } = readTicketDocument(opts.cwd, targetEntry, { action: "ticket close", requireExists: true });
+  const parsedForClose = { meta: closeMeta, content: closeContent };
   const closePlanningReasons = getCloseLifecycleReasons(parsedForClose.meta, parsedForClose.content);
   const implementationGuard = getImplementationClaimGuardResult(opts.cwd, { content: parsedForClose.content, changedFiles: opts.changedFiles });
   if (!implementationGuard.ok) {
@@ -1808,7 +1859,7 @@ export async function runTicketClose(opts) {
       syncActiveTicketId(opts.cwd);
     }
 
-    const finalPath = archiveResult?.path || entry.path;
+    const finalPath = archiveResult?.path || computeTicketPath(entry);
     appendTelemetryEvent(opts.cwd, {
       event: "ticket_closed",
       action: "ticket-close",
@@ -1868,25 +1919,23 @@ export async function runTicketUse(opts) {
     throw new Error(buildUseNoMatchError(targetTopic, candidates));
   }
 
-  const foundAbsPath = join(opts.cwd, found.path);
-  if (!existsSync(foundAbsPath)) throw new Error("Ticket file not found: " + found.path);
-  const foundParsed = parseFrontMatter(readFileSync(foundAbsPath, "utf8"));
-  assertTicketLifecycleProvenance(found, foundParsed.meta);
+  const foundDoc = readTicketDocument(opts.cwd, found, { action: "ticket use", requireExists: true });
+  assertTicketLifecycleProvenance(found, foundDoc.meta);
   
   // Explicitly set activeTicketId to the selected ticket
   if (index.activeTicketId !== found.id) {
     writeTicketIndexJson(opts.cwd, { ...index, activeTicketId: found.id });
   }
 
-  const absPath = toPosixPath(join(opts.cwd, found.path));
+  const absPath = toPosixPath(foundDoc.absPath);
   if (isCompactTicketOutput(opts) || opts.pathOnly) {
     printTicketSelectionLine(found.id, absPath, opts);
   } else {
-    const posixPath = toPosixPath(found.path);
+    const posixPath = toRepoRelativePath(opts.cwd, foundDoc.absPath);
     console.log(`Active ticket: ${found.id}`);
     console.log(`Path: [${posixPath}](file://${absPath})`);
     printTicketStartLine(found.id, absPath);
-    if (opts.printContent) console.log("\n" + readFileSync(join(opts.cwd, found.path), "utf8"));
+    if (opts.printContent) console.log("\n" + readFileSync(foundDoc.absPath, "utf8"));
     printUsageReminder(opts.cwd, opts);
   }
 }
@@ -1920,7 +1969,7 @@ function distillKnowledge(absPath, ticketId, cwd, sourceBody = null) {
       "Design Decisions",
       "Analysis & Constraints"
     ]);
-    const knowledgeDir = join(cwd, AGENT_ROOT_DIR, "knowledge");
+    const knowledgeDir = resolveTicketKnowledgeDir(cwd);
     if (!existsSync(knowledgeDir)) mkdirSync(knowledgeDir, { recursive: true });
 
     const dest = join(knowledgeDir, `${ticketId}.json`);
@@ -2034,12 +2083,12 @@ export async function runTicketArchive(opts) {
   const found = pickTicketEntry(opts, indexJson);
   if (!found) throw new Error("ticket archive: no matching entry");
 
-  const fileName = found.path.split(/[/\\]/).pop();
+  const fileName = (found.path || computeTicketPath(found)).split(/[/\\]/).pop();
   
   // Auto-search for report if not provided
   let report = opts.report;
   if (!opts.report) {
-    const reportDir = join(opts.cwd, AGENT_ROOT_DIR, "docs", "plan");
+    const reportDir = resolveTicketReportDir(opts.cwd);
     const potentialReport = fileName.replace(/\.md$/i, "-report.md");
     const potentialPath = join(reportDir, potentialReport);
     if (existsSync(potentialPath)) {
@@ -2089,8 +2138,9 @@ export async function runTicketDiscard(opts) {
   const found = pickTicketEntry(opts, indexJson);
   if (!found) throw new Error("ticket discard: no matching entry");
 
-  const absPath = join(opts.cwd, found.path);
-  if (!existsSync(absPath)) throw new Error("Ticket file not found: " + found.path);
+  const absPath = resolveTicketEntryOrComputedPath(opts.cwd, found);
+  const relativePath = toRepoRelativePath(opts.cwd, absPath);
+  if (!existsSync(absPath)) throw new Error("Ticket file not found: " + relativePath);
 
   const body = readFileSync(absPath, "utf8");
   const { meta } = parseFrontMatter(body);
@@ -2101,8 +2151,8 @@ export async function runTicketDiscard(opts) {
   }
 
   if (opts.dryRun) {
-    console.log(`ticket discard: would delete ${found.id || found.topic} (${found.path})`);
-    return { id: found.id, path: found.path, discarded: false };
+    console.log(`ticket discard: would delete ${found.id || found.topic} (${relativePath})`);
+    return { id: found.id, path: relativePath, discarded: false };
   }
 
   rmSync(absPath, { force: true });
@@ -2117,19 +2167,19 @@ export async function runTicketDiscard(opts) {
     event: "ticket_discarded",
     action: "ticket-discard",
     ticket: found.id || found.topic,
-    file: found.path,
+    file: relativePath,
     phase,
     status: "discarded"
   });
   console.log(`ticket: discarded -> ${found.id || found.topic}`);
-  return { id: found.id, path: found.path, discarded: true };
+  return { id: found.id, path: relativePath, discarded: true };
 }
 
 export async function runTicketReports(opts) {
   applyTicketRootContext(opts);
   const ticketDir = detectConsumerTicketDir(opts.cwd);
   if (!ticketDir) throw new Error("No ticket system found.");
-  const reportDir = join(opts.cwd, AGENT_ROOT_DIR, "docs", "plan");
+  const reportDir = resolveTicketReportDir(opts.cwd);
   console.log("\n📄 Agent Reports:");
   if (!existsSync(reportDir)) {
     console.log("  No reports found.");
@@ -2164,16 +2214,15 @@ export async function runTicketReportAttach(opts) {
   const found = pickTicketEntry(opts, index);
   if (!found) throw new Error("ticket report attach: no matching ticket found");
 
-  const absTicketPath = join(opts.cwd, found.path);
-  if (!existsSync(absTicketPath)) throw new Error("Ticket file not found: " + found.path);
+  const { absPath: absTicketPath } = readTicketDocument(opts.cwd, found, { action: "ticket report attach", requireExists: true });
 
   const reportSrc = resolve(opts.cwd, opts.report);
   if (!existsSync(reportSrc)) throw new Error("Report file not found: " + opts.report);
 
-  const reportDir = join(opts.cwd, AGENT_ROOT_DIR, "docs", "plan");
+  const reportDir = resolveTicketReportDir(opts.cwd);
   if (!opts.dryRun) mkdirSync(reportDir, { recursive: true });
 
-  const ticketFileName = found.path.split(/[/\\]/).pop();
+  const ticketFileName = (found.path || computeTicketPath(found)).split(/[/\\]/).pop();
   const reportBaseName = ticketFileName.replace(/\.md$/i, "-report.md");
   const reportDest = join(reportDir, reportBaseName);
 
@@ -2214,15 +2263,17 @@ export async function runTicketMove(opts) {
   
   if (!entry) throw new Error("No matching ticket found to move.");
 
-  const abs = join(opts.cwd, entry.path);
-  if (!existsSync(abs)) throw new Error("Ticket file not found: " + entry.path);
+  const { absPath: abs, meta: parsedMeta, content } = readTicketDocument(opts.cwd, entry, { action: "ticket move", requireExists: true });
 
   const previousIndex = readTicketIndexJson(opts.cwd);
   const body = readFileSync(abs, "utf8");
-  const { meta, content } = parseFrontMatter(body);
-
-  const currentPhase = meta.phase || 1;
-  let nextPhase = opts.next ? currentPhase + 1 : (opts.phase || currentPhase + 1);
+  const currentPhase = Number(parsedMeta.phase || 1);
+  const requestedPhase = Number(opts.phase);
+  let nextPhase = opts.next
+    ? currentPhase + 1
+    : Number.isFinite(requestedPhase)
+      ? requestedPhase
+      : currentPhase + 1;
 
   if (currentPhase === 1 && nextPhase >= 2) {
     const reasons = getPhase1IncompleteReasons(opts.cwd, abs);
@@ -2238,22 +2289,22 @@ export async function runTicketMove(opts) {
     }
   }
 
-  meta.phase = nextPhase;
+  parsedMeta.phase = nextPhase;
   if (nextPhase >= 4) {
-    meta.status = "closed";
-  } else if (nextPhase >= 2 && (!meta.status || meta.status === "open")) {
-    meta.status = "active";
+    parsedMeta.status = "closed";
+  } else if (nextPhase >= 2 && (!parsedMeta.status || parsedMeta.status === "open")) {
+    parsedMeta.status = "active";
   }
 
-  const newBody = stringifyFrontMatter(meta, content);
+  const newBody = stringifyFrontMatter(parsedMeta, content);
 
   try {
     writeFileSync(abs, newBody, "utf8");
 
     // Re-sync index to reflect the status change if any
     opts.topic = entry.topic;
-    if (meta.status !== entry.status) {
-      opts.status = meta.status;
+    if (parsedMeta.status !== entry.status) {
+      opts.status = parsedMeta.status;
       updateTicketEntryStatus(opts.cwd, opts);
     } else {
       rebuildTicketIndexFromTopicFilesIfNeeded(opts.cwd, { ...opts, force: true });
@@ -2269,11 +2320,11 @@ export async function runTicketMove(opts) {
       event: "ticket_phase_moved",
       action: "ticket-move",
       ticket: entry.id || entry.topic,
-      file: entry.path,
+      file: computeTicketPath(entry),
       phase: nextPhase,
-      status: meta.status
+      status: parsedMeta.status
     });
-    console.log(`ticket: moved -> ${entry.topic} is now in Phase ${nextPhase} (${meta.status})`);
+    console.log(`ticket: moved -> ${entry.topic} is now in Phase ${nextPhase} (${parsedMeta.status})`);
     printUsageReminder(opts.cwd, opts);
   } catch (err) {
     rollbackTicketLifecycleArtifacts(opts.cwd, previousIndex, body, abs, opts);
@@ -2298,9 +2349,9 @@ export async function runTicketNext(opts) {
       .filter(entry => String(entry.status || "").toLowerCase() === "closed")
       .sort((a, b) => String(b.updatedAt || b.createdAt || "").localeCompare(String(a.updatedAt || a.createdAt || "")))[0];
     if (latestClosed) {
-      const latestClosedPath = join(opts.cwd, latestClosed.path || computeTicketPath(latestClosed));
+      const latestClosedPath = resolveTicketEntryOrComputedPath(opts.cwd, latestClosed);
       if (existsSync(latestClosedPath)) {
-        const { content } = parseFrontMatter(readFileSync(latestClosedPath, "utf8"));
+        const { content } = readTicketDocument(opts.cwd, latestClosed, { action: "ticket next", computePath: true });
         if (followUpDecisionMeansNoFollowUp(content)) {
           const absPath = toPosixPath(latestClosedPath);
           if (opts.pathOnly) {
@@ -2308,7 +2359,7 @@ export async function runTicketNext(opts) {
           } else if (isCompactTicketOutput(opts)) {
             console.log(`no-follow-up:${latestClosed.id}`);
           } else {
-            const posixPath = toPosixPath(latestClosed.path || computeTicketPath(latestClosed));
+            const posixPath = toPosixPath(toRepoRelativePath(opts.cwd, latestClosedPath));
             console.log(`No follow-up required after ${latestClosed.id}`);
             console.log(`Path: [${posixPath}](file://${absPath})`);
           }
@@ -2323,23 +2374,23 @@ export async function runTicketNext(opts) {
     writeTicketIndexJson(opts.cwd, { ...index, activeTicketId: found.id });
   }
 
-  const absPath = toPosixPath(join(opts.cwd, found.path));
+  const foundAbs = readTicketDocument(opts.cwd, found, { action: "ticket next", requireExists: true });
+  const absPath = toPosixPath(foundAbs.absPath);
   if (isCompactTicketOutput(opts) || opts.pathOnly) {
     printTicketSelectionLine(found.id, absPath, opts);
   } else {
-    const posixPath = toPosixPath(found.path);
+    const posixPath = toPosixPath(toRepoRelativePath(opts.cwd, foundAbs.absPath));
     console.log(`Next ticket: ${found.id}`);
     console.log(`Path: [${posixPath}](file://${absPath})`);
-    if (opts.printContent) console.log("\n" + readFileSync(join(opts.cwd, found.path), "utf8"));
+      if (opts.printContent) console.log("\n" + readFileSync(foundAbs.absPath, "utf8"));
   }
 }
 
 function isTicketNextRunnableCandidate(cwd, entry) {
-  const entryPath = entry.path || computeTicketPath(entry);
-  const absPath = join(cwd, entryPath);
-  if (!existsSync(absPath)) return true;
+  const ticketDoc = readTicketDocument(cwd, entry, { action: "ticket next", computePath: true, requireExists: false });
+  if (!ticketDoc.exists) return true;
 
-  const { meta } = parseFrontMatter(readFileSync(absPath, "utf8"));
+  const { meta } = ticketDoc;
   const lifecycleSource = String(meta.lifecycleSource || meta.ticketLifecycleSource || "").trim();
   return lifecycleSource === "ticket-create";
 }
@@ -2378,11 +2429,7 @@ export async function runTicketHotfix(opts) {
   
   if (!entry) throw new Error("No matching ticket found for hotfix.");
 
-  const abs = join(opts.cwd, entry.path);
-  if (!existsSync(abs)) throw new Error("Ticket file not found: " + entry.path);
-
-  const body = readFileSync(abs, "utf8");
-  const { meta, content } = parseFrontMatter(body);
+  const { absPath: abs, meta, content } = readTicketDocument(opts.cwd, entry, { action: "ticket hotfix", requireExists: true });
 
   // Force phase 2 and active status, bypassing APC checks
   meta.phase = 2;