deuk-agent-flow 4.2.7 → 5.0.2

package/scripts/cli-ticket-index.ts

@@ -0,0 +1,283 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, renameSync, statSync } from "fs";
+import { basename, dirname, resolve } from "path";
+import {
+  DEUK_ROOT_DIR, TICKET_SUBDIR, TICKET_INDEX_FILENAME,
+  requireNonEmptySlug, findFileRecursively, toRepoRelativePath, detectConsumerTicketDir, computeTicketPath, normalizeTicketGroup, writeFileLF, makePath, resolveWorkspaceContext
+ , CliOpts } from "./cli-utils.js";
+import { collectTicketEntriesFromTopicFiles } from "./cli-ticket-scan.js";
+
+const ARCHIVE_INDEX_MONTH_RE = /^INDEX\.archive\.(\d{4}-\d{2})\.json$/;
+const ARCHIVE_INDEX_LEGACY_RE = /^INDEX\.archive\.json$/;
+
+function parseNextTicketSequence(value) {
+  const raw = Number(value);
+  if (!Number.isInteger(raw) || raw < 1) return null;
+  return raw;
+}
+
+function maxTicketNumberFromEntries(entries = []) {
+  const newRe = /^([0-9]{3,4})-/;
+  let max = 0;
+  for (const e of (entries || [])) {
+    const id = String(e.id || '');
+    const m = id.match(newRe);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return max;
+}
+
+function normalizeNextTicketSequence(nextTicketSequence, entries = []) {
+  const fallbackNum = maxTicketNumberFromEntries(entries);
+  const fallbackNext = fallbackNum < 9999 ? (fallbackNum + 1) : fallbackNum;
+  const parsed = parseNextTicketSequence(nextTicketSequence);
+  if (parsed === null) return fallbackNext || 1;
+  return Math.max(parsed, fallbackNext || 1);
+}
+
+function writeJsonFileAtomically(absPath, data) {
+  const serialized = JSON.stringify(data, null, 2) + "\n";
+  const tmpPath = `${absPath}.tmp-${process.pid}-${Date.now()}`;
+  writeFileLF(tmpPath, serialized);
+  try {
+    renameSync(tmpPath, absPath);
+  } catch (err) {
+    // POSIX rename(2)은 대상을 원자적으로 덮어쓰지만, Windows renameSync는 대상이
+    // 이미 있으면 EEXIST/EPERM으로 throw한다. 그 경우 대상을 먼저 지우고 재시도하고,
+    // 그래도 실패하면 직접 덮어쓰기로 폴백한다. 어느 경로든 tmp는 남기지 않는다.
+    try {
+      if (existsSync(absPath)) {
+        unlinkSync(absPath);
+        renameSync(tmpPath, absPath);
+      } else {
+        throw err;
+      }
+    } catch {
+      writeFileLF(absPath, serialized);
+      if (existsSync(tmpPath)) {
+        try { unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
+      }
+    }
+  }
+}
+
+function listArchiveIndexFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(ent => ent.isFile())
+    .map(ent => makePath(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, nextTicketSequence: 1, 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;
+    }) : [];
+    // activeTicketId/activeTickets are no longer read from INDEX.json — focus is
+    // owned solely by the marker file. Any legacy fields on disk are ignored.
+    return {
+      version: j.version || 1,
+      updatedAt: j.updatedAt ?? null,
+      nextTicketSequence: parseNextTicketSequence(j.nextTicketSequence),
+      entries
+    };
+  } catch (err) {
+    console.error(`[ERROR] Failed to parse ${basename(absPath)} at ${absPath}:`, err.message);
+    return { version: 1, updatedAt: null, nextTicketSequence: 1, entries: [], _corrupt: true };
+  }
+}
+
+function getWorkspaceKey(cwd) {
+  return resolveWorkspaceContext(cwd).breadcrumb;
+}
+
+function getWorkspaceSlug(cwd) {
+  const key = getWorkspaceKey(cwd);
+  return key.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'default';
+}
+
+function splitEntriesForStorage(entries = []) {
+  const activeEntries = [];
+  const archiveEntries = [];
+  for (const entry of entries) {
+    const status = String(entry?.status || "open").toLowerCase();
+    const phase = Number(entry?.phase || 1);
+    if ((status === "open" || status === "active") && phase < 4 && !entry?.archiveYearMonth) {
+      activeEntries.push(entry);
+    } else {
+      archiveEntries.push(entry);
+    }
+  }
+  return { activeEntries, archiveEntries };
+}
+
+
+export function readTicketIndexJson(cwd) {
+  const dir = detectConsumerTicketDir(cwd);
+  if (!dir) return { version: 1, updatedAt: null, entries: [] };
+  const mainPath = makePath(dir, TICKET_INDEX_FILENAME);
+  const main = parseIndexFile(mainPath);
+
+  // The pointer file no longer stores entries — the ticket list is derived from
+  // the .md files (single source of truth). Scan them here so every consumer of
+  // readTicketIndexJson still sees a populated entry list.
+  const entries = collectTicketEntriesFromTopicFiles(cwd).map(entry => {
+    const next: Record<string, any> = { ...entry, status: entry.status || "open", group: normalizeTicketGroup(entry.group, "sub") };
+    next.path = computeTicketPath(next);
+    return next;
+  });
+
+  // #685: LangGraph 모델 — state(현재 노드)는 .md 프론트매터(phase/status)가 유일 SSOT.
+  // sessionId/쿠키/claim 폴백 레이어는 전면 제거됨. 현재 노드(activeTicketId)는 디스크의
+  // .md 스캔 결과에서 결정적으로 도출한다: live = (open/active) AND phase<4.
+  // 여러 개 live면 가장 진행된 노드(phase 높은 것, 동률이면 최신 createdAt)가 현재 노드.
+  // 값이 없으면 폴백이 아니라 "현재 노드 없음(null) = START 진입점"이다.
+  const liveEntries = entries.filter(e => {
+    const status = String(e.status || "open").toLowerCase();
+    return (status === "open" || status === "active") && Number(e.phase || 1) < 4 && !e.archiveYearMonth;
+  });
+  const sortedLive = [...liveEntries].sort((a, b) => {
+    const phaseDiff = Number(b.phase || 1) - Number(a.phase || 1);
+    if (phaseDiff !== 0) return phaseDiff;
+    return String(b.createdAt || "").localeCompare(String(a.createdAt || ""));
+  });
+  const activeTicketId = sortedLive.length > 0 ? sortedLive[0].id : null;
+
+  return {
+    version: main.version || 1,
+    updatedAt: main.updatedAt ?? null,
+    activeTicketId,
+    liveTicketIds: sortedLive.map(e => e.id),
+    nextTicketSequence: normalizeNextTicketSequence(main.nextTicketSequence, entries),
+    entries,
+    _corrupt: Boolean(main._corrupt)
+  };
+}
+
+export function writeTicketIndexJson(cwd, indexJson, opts: CliOpts = {}) {
+  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 = makePath(dir, TICKET_INDEX_FILENAME);
+  if (opts.dryRun) return;
+  mkdirSync(dir, { recursive: true });
+  
+  // The pointer file is a THIN focus-state file. The ticket list itself is
+  // derived from .md files (the single source of truth), so we never persist
+  // entries or per-month archive index files. We keep only the two facts that
+  // cannot be re-derived from .md alone: the focus pointer (activeTicketId) and
+  // the monotonically increasing next ticket number (nextTicketSequence).
+  const entries = Array.isArray(indexJson.entries) ? indexJson.entries : [];
+
+  const currentDiskState = parseIndexFile(p);
+
+  // nextTicketSequence must never go backwards: max of the stored pointer and
+  // (highest known ticket number across ALL entries, active or archived) + 1.
+  const callerNextSequence = normalizeNextTicketSequence(indexJson.nextTicketSequence, entries);
+  const diskNextSequence = normalizeNextTicketSequence(currentDiskState.nextTicketSequence, entries);
+  const nextTicketSequence = Math.max(callerNextSequence, diskNextSequence);
+
+  const out = {
+    version: indexJson.version || 1,
+    updatedAt: indexJson.updatedAt || new Date().toISOString(),
+    // activeTickets is deliberately omitted to prevent centralized contention
+    nextTicketSequence
+  };
+  writeJsonFileAtomically(p, out);
+
+  // Remove any legacy per-month archive index files — entries are no longer
+  // persisted, so these stale duplicates must not linger.
+  for (const filePath of listArchiveIndexFiles(dir)) {
+    unlinkSync(filePath);
+  }
+}
+
+// #675: Claims ticketId for the current session using cookie touch file.
+// Pass ticketId=null to release.
+export function setActiveTicketMarker(cwd, ticketId, opts: CliOpts = {}) {
+  // #685: LangGraph 모델 — 현재 노드는 .md phase가 SSOT다. 노드 위치를 쿠키/마커에
+  // 별도 저장하지 않는다(폴백 레이어 전면 제거). 이 함수는 하위 호환을 위한 no-op이며,
+  // 노드 이동은 ticket move가 .md phase를 갱신하는 것으로만 일어난다.
+  return;
+}
+
+// #685: getHostnameSlug 제거 — 티켓 ID에서 hostname suffix를 뺐으므로 불필요(언니 지시).
+
+// #685: claim/actor/세션 마커 레이어 전면 제거 — LangGraph 모델에서 현재 노드는 .md
+// phase가 SSOT이고 단일 사용자 환경이라 "누가 티켓을 잡았나" 추적이 불필요하다.
+// resolveActor/readClaim/writeClaim/releaseClaim/isClaimStale/migrateLegacyActiveMarkers
+// (전부 sessionId 쿠키 폴백 의존)와 CLAIM_STALE_MS를 삭제했다.
+
+export function computeNextTicketNumber(indexState) {
+  const maybeEntries = Array.isArray(indexState) ? indexState : indexState?.entries;
+  const parsedNext = normalizeNextTicketSequence(indexState?.nextTicketSequence, maybeEntries);
+  return { num: parsedNext };
+}
+
+export function generateTicketId(titleSlug, indexState) {
+  // #685: 티켓 ID의 hostname suffix(-joy-deep 등) 제거 — 단일 환경이라 호스트 구분이
+  // 무의미하다(언니 지시). ID는 {num}-{slug}로만 구성한다.
+  const slug = requireNonEmptySlug(titleSlug, "ticket title");
+  const match = slug.match(/^(\d{3,4})-(.*)/);
+  const idSlug = match ? requireNonEmptySlug(match[2], "ticket title") : slug;
+  if (/^\d{3,4}$/.test(idSlug)) {
+    throw new Error("[VALIDATION FAILED] ticket title must include a non-numeric slug; ticket numbers are assigned by INDEX nextTicketSequence.");
+  }
+  const { num } = computeNextTicketNumber(indexState);
+  const numStr = String(num).padStart(3, '0');
+  const finalSlug = idSlug.slice(0, 32);
+  return `${numStr}-${finalSlug}`;
+}
+
+export function syncActiveTicketId(cwd, opts: CliOpts = {}) {
+  // #685: LangGraph 모델 — 현재 노드는 .md phase가 SSOT라 마커 동기화가 불필요하다.
+  // 이 함수는 이제 레거시 포인터 파일(LATEST.md/ACTIVE_TICKET.*) 정리만 담당한다.
+  const ticketDir = detectConsumerTicketDir(cwd);
+  if (!ticketDir) return;
+  if (opts.dryRun) return;
+
+  const legacyLatestPath = makePath(ticketDir, "LATEST.md");
+  const pointerPathMd = makePath(ticketDir, "ACTIVE_TICKET.md");
+  const pointerPathJson = makePath(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 → cli-ticket-migration.ts}

@@ -1,11 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync, statSync } from "fs";
-import { basename, dirname, join, relative } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync, renameSync } from "fs";
+import { basename, dirname } 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";
+  toRepoRelativePath, TICKET_SUBDIR, TICKET_LIST_FILENAME,
+  parseFrontMatter, findFileRecursively, detectConsumerTicketDir, makePath
+ , CliOpts } from "./cli-utils.js";
+import { readTicketIndexJson, syncActiveTicketId, writeTicketIndexJson } from "./cli-ticket-index.js";
+import { collectTicketMarkdownFiles, rebuildTicketIndexFromTopicFilesIfNeeded } from "./cli-ticket-parser.js";
+import { splitTicketDocMetaSection } from "./cli-ticket-docmeta.js";
+import { writeTicketDocument } from "./cli-ticket-document.js";
 
 // ─── Summary Extraction ─────────────────────────────────────────────────────
 
@@ -22,7 +24,7 @@ export function extractSummary(meta, content) {
   const lines = content.split("\n");
 
   // Collect section contents by known header patterns
-  const sections = {};
+  const sections: Record<string, any> = {};
   let currentSection = null;
   for (const line of lines) {
     const trimmed = line.trim();
@@ -147,7 +149,7 @@ export function ensureCautionBlock(content) {
 
 // ─── Main Migration ─────────────────────────────────────────────────────────
 
-export function performUpgradeMigration(cwd, opts = {}) {
+export function performUpgradeMigration(cwd, opts: CliOpts = {}) {
   const root = detectConsumerTicketDir(cwd, { createIfMissing: true });
   
   const files = collectTicketMarkdownFiles(root).filter(p => {
@@ -191,8 +193,8 @@ export function performUpgradeMigration(cwd, opts = {}) {
     // 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");
+      const ticketDocMeta = splitTicketDocMetaSection(modifiedContent);
+      writeTicketDocument(finalAbs, { meta, content: ticketDocMeta.body, docmeta: ticketDocMeta.docmeta });
       upgraded++;
       console.log(`[OK] Upgraded + archived: ${toRepoRelativePath(cwd, finalAbs)}`);
       continue;
@@ -205,8 +207,8 @@ export function performUpgradeMigration(cwd, opts = {}) {
         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");
+        const ticketDocMeta = splitTicketDocMetaSection(modifiedContent);
+        writeTicketDocument(abs, { meta, content: ticketDocMeta.body, docmeta: ticketDocMeta.docmeta });
         upgraded++;
       }
     }
@@ -216,67 +218,26 @@ export function performUpgradeMigration(cwd, opts = {}) {
 
   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);
-    }
-  }
-}
+// #727: performDefragmentation 제거 — 홈 uuid 스토어의 티켓을 meta.submodule 기준으로
+// 서브모듈 .deuk/tickets 로 역이동(cwd write)시켜 홈 일원화(#622)를 되돌리던 코드였다.
+// normalizeTicketPaths 주석('티켓은 홈에 산다, cwd로 끌어내면 안 됨')과 정면 모순이라
+// 함수와 호출(upgrade 흐름)을 통째로 제거. 티켓은 홈에만 산다.
 
 // ─── Utilities ──────────────────────────────────────────────────────────────
 
 export function moveFileToArchive(cwd, abs, group) {
   const ticketDir = detectConsumerTicketDir(cwd);
-  const archiveBase = join(ticketDir, "archive");
+  const archiveBase = makePath(ticketDir, "archive");
   const targetSubDir = (basename(ticketDir) === TICKET_SUBDIR || !group) ? "sub" : group;
-  const targetDir = join(archiveBase, targetSubDir);
+  const targetDir = makePath(archiveBase, targetSubDir);
   mkdirSync(targetDir, { recursive: true });
-  const finalAbs = join(targetDir, basename(abs));
+  const finalAbs = makePath(targetDir, basename(abs));
   if (finalAbs !== abs) {
     if (existsSync(finalAbs)) {
       unlinkSync(abs);
@@ -288,7 +249,7 @@ export function moveFileToArchive(cwd, abs, group) {
   return finalAbs;
 }
 
-export function normalizeTicketPaths(cwd, opts = {}) {
+export function normalizeTicketPaths(cwd, opts: CliOpts = {}) {
   const index = readTicketIndexJson(cwd);
   const ticketDir = detectConsumerTicketDir(cwd);
   const entries = index.entries || [];
@@ -296,15 +257,30 @@ export function normalizeTicketPaths(cwd, opts = {}) {
 
   for (const entry of entries) {
     if (!entry.path) continue;
-    
-    const currentAbs = join(cwd, entry.path);
+
+    // #622/#623: 티켓 .md는 cwd(워크스페이스 git 트리)가 아니라 홈 ticketDir에 산다.
+    // 정상 위치는 makePath(ticketDir, entry.path)이다. entry.path를 cwd 기준으로 해석해
+    // 그쪽으로 옮기면, 홈에 멀쩡히 있던 .md를 워크스페이스로 끌어내 홈 디렉토리를 비우고
+    // (그 순간 rebuild 스캔이 entries=0을 보고 active claim을 고아로 오인해 삭제한다).
+    // 따라서 파일이 이미 ticketDir 하위에 있으면 그게 올바른 위치이므로 이동하지 않는다.
+    const canonicalAbs = makePath(ticketDir, entry.path);
+    if (existsSync(canonicalAbs)) continue;
+
+    const currentAbs = makePath(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;
+        // 발견된 파일이 이미 홈 ticketDir 하위면 정상 위치 — 워크스페이스로 옮기지 않는다.
+        const destAbs = canonicalAbs;
+        if (found !== destAbs) {
+          mkdirSync(dirname(destAbs), { recursive: true });
+          try {
+            renameSync(found, destAbs);
+          } catch {
+            copyFileSync(found, destAbs);
+            unlinkSync(found);
+          }
           modified = true;
         }
       }

package/scripts/cli-ticket-parser.ts

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync } from "fs";
+import {
+  parseFrontMatter, discoverAllWorkspaces, detectConsumerTicketDir, computeTicketPath, makePath
+ , CliOpts } from "./cli-utils.js";
+import { readTicketIndexJson, writeTicketIndexJson } from "./cli-ticket-index.js";
+import { splitTicketDocMetaSection } from "./cli-ticket-docmeta.js";
+import { writeTicketDocument } from "./cli-ticket-document.js";
+
+export { collectTicketMarkdownFiles } from "./cli-ticket-scan.js";
+
+export function discoverAllTicketDirs(baseCwd, out = []) {
+  return discoverAllWorkspaces(baseCwd, undefined, new Set(out));
+}
+
+export function rebuildTicketIndexFromTopicFilesIfNeeded(cwd, opts: CliOpts = {}) {
+  // readTicketIndexJson already derives entries from the .md files (single source
+  // of truth) and merges in the thin pointer state (activeTicketId/nextTicketSequence).
+  const indexJson = readTicketIndexJson(cwd);
+
+  const ticketDir = detectConsumerTicketDir(cwd);
+  if (!ticketDir) return indexJson;
+
+  // Persist the thin pointer file so activeTicketId/nextTicketSequence are kept in
+  // sync on disk. writeTicketIndexJson stores ONLY the pointer state, never entries.
+  writeTicketIndexJson(cwd, indexJson, indexJson._corrupt ? { ...opts, force: true } : opts);
+  if (opts.rebuild) console.log(`[REBUILD] Ticket pointer synced; ${indexJson.entries.length} entries derived from .md.`);
+  return indexJson;
+}
+
+export function appendTicketEntry(cwd, entry, opts: CliOpts = {}) {
+  const indexJson = readTicketIndexJson(cwd);
+  entry.status = entry.status || "open";
+  // We no longer store 'path' snapshots in INDEX.json
+  const { path, ...cleanEntry } = entry;
+  const next = { 
+    version: indexJson.version || 1, 
+    updatedAt: new Date().toISOString(), 
+    activeTicketId: indexJson.activeTicketId, 
+    entries: [cleanEntry, ...indexJson.entries] 
+  };
+  writeTicketIndexJson(cwd, next, opts);
+}
+
+export function updateTicketEntryStatus(cwd, opts: CliOpts = {}) {
+  const indexJson = rebuildTicketIndexFromTopicFilesIfNeeded(cwd, opts);
+  let foundIndex = -1;
+  const targetId = opts.ticketId ? String(opts.ticketId).toLowerCase() : null;
+  
+  if (opts.latest) {
+    foundIndex = 0;
+  } else if (targetId) {
+    foundIndex = indexJson.entries.findIndex(e =>
+      String(e.id || "").toLowerCase().includes(targetId)
+    );
+  }
+
+  if (foundIndex === -1) {
+    throw new Error("No matching ticket found to update status");
+  }
+
+  const entry = indexJson.entries[foundIndex];
+  const newStatus = opts.status || "closed";
+  entry.status = newStatus;
+  if (newStatus === "open" || newStatus === "active") {
+    delete entry.archiveYearMonth;
+    delete entry.archiveDay;
+  }
+  if (newStatus === "closed" || newStatus === "completed" || newStatus === "cancelled" || newStatus === "wontfix") {
+    entry.phase = 4;
+  }
+  entry.updatedAt = new Date().toISOString();
+  
+  // Sync status back to .md frontmatter to prevent rebuild reversion.
+  // #736: cwd is the WORKSPACE root; tickets live in the HOME store (detectConsumerTicketDir).
+  // makePath(workspaceRoot, relativePath) misses the file → use the ticket dir as base.
+  const entryPath = entry.path || computeTicketPath(entry);
+  const ticketDir = detectConsumerTicketDir(cwd) || cwd;
+  const absPath = makePath(ticketDir, entryPath);
+  if (existsSync(absPath)) {
+    try {
+      const body = readFileSync(absPath, "utf8");
+      const parsed = parseFrontMatter(body);
+      if (parsed.parseError) throw new Error(parsed.parseError);
+      if (parsed.meta.status !== newStatus) {
+        parsed.meta.status = newStatus;
+        if (newStatus === "closed" || newStatus === "completed" || newStatus === "cancelled" || newStatus === "wontfix") {
+          parsed.meta.phase = 4;
+        }
+        const ticketDocMeta = splitTicketDocMetaSection(parsed.content || "");
+        writeTicketDocument(absPath, { meta: parsed.meta, content: ticketDocMeta.body, docmeta: ticketDocMeta.docmeta });
+      }
+    } catch (err) {
+      console.warn(`[WARNING] Failed to sync status to ${entryPath}: ${err.message}`);
+    }
+  }
+
+  const next = { version: indexJson.version, updatedAt: new Date().toISOString(), entries: indexJson.entries };
+  writeTicketIndexJson(cwd, next, opts);
+  return entry;
+}