@hanna84/mcp-writing 3.9.4 → 3.10.0

package/CHANGELOG.md

@@ -4,9 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v3.10.0](https://github.com/hannasdev/mcp-writing/compare/v3.9.5...v3.10.0)
+
+- feat: add read-only structure diagnostics [`#202`](https://github.com/hannasdev/mcp-writing/pull/202)
+
+#### [v3.9.5](https://github.com/hannasdev/mcp-writing/compare/v3.9.4...v3.9.5)
+
+> 18 May 2026
+
+- refactor(sync): complete target architecture M3 [`#201`](https://github.com/hannasdev/mcp-writing/pull/201)
+- Release 3.9.5 [`9cd308a`](https://github.com/hannasdev/mcp-writing/commit/9cd308aa838a7c3992183ee8c0acce53d61f75cd)
+
 #### [v3.9.4](https://github.com/hannasdev/mcp-writing/compare/v3.9.3...v3.9.4)
 
+> 17 May 2026
+
 - refactor(structure): centralize scene structure patches [`#200`](https://github.com/hannasdev/mcp-writing/pull/200)
+- Release 3.9.4 [`ac77e80`](https://github.com/hannasdev/mcp-writing/commit/ac77e801d94ca576923a46a6d22c8f3230988d76)
 
 #### [v3.9.3](https://github.com/hannasdev/mcp-writing/compare/v3.9.2...v3.9.3)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.9.4",
+  "version": "3.10.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/structure/structure-diagnostics.js

@@ -0,0 +1,380 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import {
+  inferChapterStructureFromPath,
+  normalizeSceneMetaForPath,
+} from "./structure-inference.js";
+
+function sidecarPath(filePath) {
+  return filePath.replace(/\.(md|txt)$/, ".meta.yaml");
+}
+
+function normalizeRelativePath(syncDir, filePath) {
+  return path.relative(syncDir, filePath).split(path.sep).join("/");
+}
+
+function isPathInsideSyncDir(syncDir, filePath) {
+  const relativePath = path.relative(path.resolve(syncDir), path.resolve(filePath));
+  return relativePath !== "" && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+}
+
+function readStructureMetadata(filePath) {
+  const sidecar = sidecarPath(filePath);
+  if (fs.existsSync(sidecar)) {
+    const raw = fs.readFileSync(sidecar, "utf8");
+    return yaml.load(raw) ?? {};
+  }
+
+  const raw = fs.readFileSync(filePath, "utf8");
+  return matter(raw).data ?? {};
+}
+
+function readObservedStructure(syncDir, filePath) {
+  const sourceMeta = readStructureMetadata(filePath);
+  const { meta } = normalizeSceneMetaForPath(syncDir, filePath, sourceMeta);
+  return {
+    meta,
+    chapterStructure: inferChapterStructureFromPath(syncDir, filePath, meta),
+  };
+}
+
+function createDiagnostic(type, message, details = {}, {
+  severity = "warning",
+  nextStep = null,
+} = {}) {
+  return {
+    type,
+    severity,
+    message,
+    details,
+    ...(nextStep ? { next_step: nextStep } : {}),
+  };
+}
+
+function addDiagnostic(diagnostics, type, message, details = {}, options = {}) {
+  diagnostics.push(createDiagnostic(type, message, details, options));
+}
+
+function countBy(items, key) {
+  const result = {};
+  for (const item of items) {
+    const value = item[key] ?? "unknown";
+    result[value] = (result[value] ?? 0) + 1;
+  }
+  return result;
+}
+
+function projectClause(projectId, alias = "") {
+  const prefix = alias ? `${alias}.` : "";
+  return projectId ? { sql: ` AND ${prefix}project_id = ?`, params: [projectId] } : { sql: "", params: [] };
+}
+
+function readIndexedSceneRows(db, projectId) {
+  const scope = projectClause(projectId);
+  return db.prepare(`
+    SELECT scene_id, project_id, chapter_id, scene_role, chapter, chapter_title, file_path
+    FROM scenes
+    WHERE 1 = 1${scope.sql}
+    ORDER BY project_id, scene_id
+  `).all(...scope.params);
+}
+
+function readIndexedEpigraphRows(db, projectId) {
+  const scope = projectClause(projectId);
+  return db.prepare(`
+    SELECT epigraph_id, project_id, chapter_id, file_path
+    FROM epigraphs
+    WHERE 1 = 1${scope.sql}
+    ORDER BY project_id, epigraph_id
+  `).all(...scope.params);
+}
+
+function diagnoseUnknownChapterLinks(db, diagnostics, projectId) {
+  const sceneScope = projectClause(projectId, "s");
+  const scenes = db.prepare(`
+    SELECT s.scene_id, s.project_id, s.chapter_id, s.file_path
+    FROM scenes s
+    LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
+    WHERE s.chapter_id IS NOT NULL AND s.chapter_id != '' AND c.chapter_id IS NULL${sceneScope.sql}
+    ORDER BY s.project_id, s.scene_id
+  `).all(...sceneScope.params);
+
+  for (const scene of scenes) {
+    addDiagnostic(
+      diagnostics,
+      "scene_unknown_chapter",
+      `Scene "${scene.scene_id}" in project "${scene.project_id}" references unknown chapter_id "${scene.chapter_id}".`,
+      {
+        project_id: scene.project_id,
+        scene_id: scene.scene_id,
+        chapter_id: scene.chapter_id,
+        file_path: scene.file_path,
+      },
+      { nextStep: "Run sync to refresh canonical chapter indexes, then use an explicit structure workflow once available if the link is still invalid." }
+    );
+  }
+
+  const epigraphScope = projectClause(projectId, "e");
+  const epigraphs = db.prepare(`
+    SELECT e.epigraph_id, e.project_id, e.chapter_id, e.file_path
+    FROM epigraphs e
+    LEFT JOIN chapters c ON c.project_id = e.project_id AND c.chapter_id = e.chapter_id
+    WHERE c.chapter_id IS NULL${epigraphScope.sql}
+    ORDER BY e.project_id, e.epigraph_id
+  `).all(...epigraphScope.params);
+
+  for (const epigraph of epigraphs) {
+    addDiagnostic(
+      diagnostics,
+      "epigraph_unknown_chapter",
+      `Epigraph "${epigraph.epigraph_id}" in project "${epigraph.project_id}" references unknown chapter_id "${epigraph.chapter_id}".`,
+      {
+        project_id: epigraph.project_id,
+        epigraph_id: epigraph.epigraph_id,
+        chapter_id: epigraph.chapter_id,
+        file_path: epigraph.file_path,
+      },
+      { nextStep: "Check the epigraph file path and chapter sidecar fields before applying any repair." }
+    );
+  }
+}
+
+function diagnoseNumericCompatibility(db, diagnostics, projectId) {
+  const scope = projectClause(projectId, "s");
+  const rows = db.prepare(`
+    SELECT s.scene_id, s.project_id, s.chapter_id, s.chapter, s.chapter_title,
+           c.sort_index, c.title
+    FROM scenes s
+    JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
+    WHERE (
+      (s.chapter IS NOT NULL AND s.chapter != c.sort_index)
+      OR (s.chapter_title IS NOT NULL AND s.chapter_title != c.title)
+    )${scope.sql}
+    ORDER BY s.project_id, s.scene_id
+  `).all(...scope.params);
+
+  for (const row of rows) {
+    addDiagnostic(
+      diagnostics,
+      "numeric_chapter_identity_mismatch",
+      `Scene "${row.scene_id}" compatibility chapter fields disagree with canonical chapter "${row.chapter_id}".`,
+      {
+        project_id: row.project_id,
+        scene_id: row.scene_id,
+        chapter_id: row.chapter_id,
+        scene_chapter: row.chapter,
+        canonical_chapter: row.sort_index,
+        scene_chapter_title: row.chapter_title,
+        canonical_chapter_title: row.title,
+      },
+      { nextStep: "Prefer canonical chapter_id in workflows; update compatibility fields only through sanctioned structure paths." }
+    );
+  }
+}
+
+function diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs }) {
+  const observedChapterFolders = new Map();
+  const roleFolders = new Map();
+
+  for (const scene of scenes) {
+    if (!scene.file_path || !fs.existsSync(scene.file_path)) continue;
+    if (!isPathInsideSyncDir(syncDir, scene.file_path)) {
+      addDiagnostic(
+        diagnostics,
+        "indexed_path_outside_sync_root",
+        `Scene "${scene.scene_id}" has an indexed file path outside the active sync root.`,
+        {
+          project_id: scene.project_id,
+          scene_id: scene.scene_id,
+          file_path: scene.file_path,
+          sync_dir: syncDir,
+        },
+        { nextStep: "Run sync with the current sync root before trusting file-derived structure diagnostics." }
+      );
+      continue;
+    }
+
+    let observed;
+    try {
+      observed = readObservedStructure(syncDir, scene.file_path);
+    } catch (error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_file_read_failed",
+        `Could not read structure metadata for scene "${scene.scene_id}": ${error.message}`,
+        {
+          project_id: scene.project_id,
+          scene_id: scene.scene_id,
+          file_path: scene.file_path,
+        },
+        { severity: "info", nextStep: "Run sync after confirming the file still exists and has readable metadata." }
+      );
+      continue;
+    }
+
+    const chapter = observed.chapterStructure.chapter;
+    if (chapter) {
+      const key = `${scene.project_id}::${chapter.sort_index}`;
+      const existing = observedChapterFolders.get(key) ?? new Set();
+      existing.add(chapter.folder_key);
+      observedChapterFolders.set(key, existing);
+
+      if (scene.chapter_id && scene.chapter_id !== chapter.chapter_id) {
+        addDiagnostic(
+          diagnostics,
+          "folder_canonical_mismatch",
+          `Scene "${scene.scene_id}" is indexed to chapter_id "${scene.chapter_id}" but its folder implies "${chapter.chapter_id}".`,
+          {
+            project_id: scene.project_id,
+            scene_id: scene.scene_id,
+            indexed_chapter_id: scene.chapter_id,
+            observed_chapter_id: chapter.chapter_id,
+            observed_chapter: chapter.sort_index,
+            relative_path: normalizeRelativePath(syncDir, scene.file_path),
+          },
+          { nextStep: "Inspect the file location and sidecar before changing canonical chapter links." }
+        );
+      }
+    }
+
+    if (observed.chapterStructure.role && ["prologue", "epilogue"].includes(observed.chapterStructure.role)) {
+      const key = `${scene.project_id}::${observed.chapterStructure.role}`;
+      const existing = roleFolders.get(key) ?? new Set();
+      existing.add(path.dirname(scene.file_path));
+      roleFolders.set(key, existing);
+    }
+  }
+
+  for (const [key, folders] of observedChapterFolders.entries()) {
+    if (folders.size <= 1) continue;
+    const [projectId, sortIndex] = key.split("::");
+    addDiagnostic(
+      diagnostics,
+      "duplicate_chapter_sort_index",
+      `Project "${projectId}" has multiple observed folders for chapter order ${sortIndex}.`,
+      {
+        project_id: projectId,
+        chapter: Number(sortIndex),
+        folders: [...folders].sort(),
+      },
+      { nextStep: "Resolve the duplicate folder-derived chapter order before relying on canonical structure diagnostics." }
+    );
+  }
+
+  for (const [key, folders] of roleFolders.entries()) {
+    if (folders.size <= 1) continue;
+    const [projectId, role] = key.split("::");
+    addDiagnostic(
+      diagnostics,
+      "multiple_scene_role",
+      `Project "${projectId}" has multiple observed ${role} folders.`,
+      {
+        project_id: projectId,
+        scene_role: role,
+        folders: [...folders].sort().map(folder => normalizeRelativePath(syncDir, folder)),
+      },
+      { nextStep: `Decide which ${role} folder is canonical before running repair or mutation workflows.` }
+    );
+  }
+
+  for (const epigraph of epigraphs) {
+    if (!epigraph.file_path || !fs.existsSync(epigraph.file_path)) continue;
+    if (!isPathInsideSyncDir(syncDir, epigraph.file_path)) {
+      addDiagnostic(
+        diagnostics,
+        "indexed_path_outside_sync_root",
+        `Epigraph "${epigraph.epigraph_id}" has an indexed file path outside the active sync root.`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          file_path: epigraph.file_path,
+          sync_dir: syncDir,
+        },
+        { nextStep: "Run sync with the current sync root before trusting file-derived structure diagnostics." }
+      );
+      continue;
+    }
+
+    let observed;
+    try {
+      observed = readObservedStructure(syncDir, epigraph.file_path);
+    } catch (error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_file_read_failed",
+        `Could not read structure metadata for epigraph "${epigraph.epigraph_id}": ${error.message}`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          file_path: epigraph.file_path,
+        },
+        { severity: "info", nextStep: "Run sync after confirming the epigraph file still exists and has readable metadata." }
+      );
+      continue;
+    }
+
+    const observedChapterId = observed.chapterStructure.chapter?.chapter_id ?? observed.meta.chapter_id ?? null;
+    if (observedChapterId && epigraph.chapter_id !== observedChapterId) {
+      addDiagnostic(
+        diagnostics,
+        "epigraph_chapter_conflict",
+        `Epigraph "${epigraph.epigraph_id}" is indexed to chapter_id "${epigraph.chapter_id}" but its file implies "${observedChapterId}".`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          indexed_chapter_id: epigraph.chapter_id,
+          observed_chapter_id: observedChapterId,
+          relative_path: normalizeRelativePath(syncDir, epigraph.file_path),
+        },
+        { nextStep: "Inspect the epigraph sidecar and folder before reassigning it." }
+      );
+    }
+  }
+}
+
+export function runStructureDiagnostics(db, {
+  syncDir,
+  projectId = null,
+} = {}) {
+  const diagnostics = [];
+  const scenes = readIndexedSceneRows(db, projectId);
+  const epigraphs = readIndexedEpigraphRows(db, projectId);
+
+  diagnoseUnknownChapterLinks(db, diagnostics, projectId);
+  diagnoseNumericCompatibility(db, diagnostics, projectId);
+
+  if (syncDir) {
+    diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs });
+  }
+
+  diagnostics.sort((a, b) => {
+    const projectCompare = String(a.details.project_id ?? "").localeCompare(String(b.details.project_id ?? ""));
+    if (projectCompare) return projectCompare;
+    const typeCompare = a.type.localeCompare(b.type);
+    if (typeCompare) return typeCompare;
+    return a.message.localeCompare(b.message);
+  });
+
+  return {
+    ok: diagnostics.length === 0,
+    checked: {
+      project_id: projectId,
+      scenes: scenes.length,
+      epigraphs: epigraphs.length,
+    },
+    summary: {
+      total: diagnostics.length,
+      by_type: countBy(diagnostics, "type"),
+      by_severity: countBy(diagnostics, "severity"),
+    },
+    diagnostics,
+    next_steps: diagnostics.length
+      ? [
+        "Review diagnostics before applying any structure repair.",
+        "Run sync after external file moves, then re-run diagnose_structure to confirm remaining drift.",
+      ]
+      : ["No structure drift detected in the current index."],
+  };
+}

package/src/sync/sync.js

@@ -74,11 +74,34 @@ export function walkSidecars(dir, fileList = []) {
   return fileList;
 }
 
+export function buildSyncDiagnostic(message, { type = null, ...details } = {}) {
+  return { type, message, ...details };
+}
+
 function isNestedMirrorPath(syncDir, filePath) {
   const rel = path.relative(syncDir, filePath).split(path.sep).join("/");
   return rel.includes("/scenes/projects/") || rel.includes("/scenes/universes/");
 }
 
+export function scanSyncFiles(syncDir) {
+  const files = [];
+  const diagnostics = [];
+
+  for (const file of walkFiles(syncDir)) {
+    if (isNestedMirrorPath(syncDir, file)) {
+      const relativePath = path.relative(syncDir, file);
+      diagnostics.push(buildSyncDiagnostic(`Ignored nested mirror path: ${relativePath}`, {
+        type: "nested_mirror",
+        relativePath,
+      }));
+      continue;
+    }
+    files.push(file);
+  }
+
+  return { files, diagnostics };
+}
+
 export function sidecarPath(filePath) {
   return filePath.replace(/\.(md|txt)$/, ".meta.yaml");
 }
@@ -813,8 +836,14 @@ export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
   return docId;
 }
 
-function pruneMissingReferenceDocs(db, seenDocIds) {
-  const rows = db.prepare(`SELECT doc_id, project_id FROM reference_docs`).all();
+function pruneMissingReferenceDocs(db, seenDocIds, syncDir) {
+  const scope = inferReferenceScopeFromSyncDir(syncDir);
+  const rows = scope?.project_id
+    ? db.prepare(`SELECT doc_id, project_id FROM reference_docs WHERE project_id = ?`).all(scope.project_id)
+    : scope?.universe_id
+      ? db.prepare(`SELECT doc_id, project_id FROM reference_docs WHERE universe_id = ?`).all(scope.universe_id)
+      : db.prepare(`SELECT doc_id, project_id FROM reference_docs`).all();
+
   for (const row of rows) {
     if (seenDocIds.has(row.doc_id)) continue;
     db.prepare(`
@@ -946,9 +975,157 @@ function pruneMissingEpigraphs(db, seenEpigraphKeys, syncDir) {
   }
 }
 
-export function indexSceneFile(db, syncDir, file, meta, prose) {
+export function pruneSyncDerivedIndexes(db, syncDir, {
+  seenSceneKeys,
+  seenEpigraphKeys,
+  seenChapterKeys,
+  sceneIndexFailures,
+}) {
+  if (!canPruneScenes(syncDir)) return { pruned: false, reason: "scope_not_prunable" };
+  if (sceneIndexFailures !== 0) return { pruned: false, reason: "scene_index_failures" };
+
+  pruneMissingScenes(db, seenSceneKeys, syncDir);
+  pruneMissingEpigraphs(db, seenEpigraphKeys, syncDir);
+  pruneMissingChapters(db, seenChapterKeys, syncDir);
+  return { pruned: true, reason: null };
+}
+
+export function regenerateReferenceAndWorldIndexes(db, syncDir, files, {
+  writable = false,
+  pruneReferenceDocs = false,
+} = {}) {
+  const indexedReferenceDocIds = new Set();
+
+  for (const file of files) {
+    if (isReferenceFile(syncDir, file)) {
+      try {
+        const { data, content } = parseFile(file);
+        const docId = indexReferenceFile(db, syncDir, file, data, content);
+        indexedReferenceDocIds.add(docId);
+      } catch (err) {
+        process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
+      }
+      continue;
+    }
+
+    if (!isWorldFile(syncDir, file)) continue;
+    try {
+      const { meta } = readMeta(file, syncDir, { writable });
+      if (!Object.keys(meta).length) {
+        const { data } = parseFile(file);
+        indexWorldFile(db, syncDir, file, data);
+      } else {
+        indexWorldFile(db, syncDir, file, meta);
+      }
+    } catch (err) {
+      process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
+    }
+  }
+
+  if (pruneReferenceDocs && canPruneReferenceDocs(syncDir)) {
+    pruneMissingReferenceDocs(db, indexedReferenceDocIds, syncDir);
+  }
+
+  return {
+    indexedReferenceDocIds,
+  };
+}
+
+export function buildStructureDiagnostic(message, { type = "chapter_structure", ...details } = {}) {
+  return { type, message, ...details };
+}
+
+export function observeStructureForFile(syncDir, file, {
+  meta = {},
+  sourceMeta = {},
+  derived = {},
+  mismatches = {},
+} = {}) {
   const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
+  const relativePath = path.relative(syncDir, file);
   const chapterStructure = inferChapterStructureFromPath(syncDir, file, meta);
+  const diagnostics = [];
+
+  if (mismatches.part || mismatches.chapter) {
+    const details = [];
+    if (mismatches.part) details.push(`part metadata ${sourceMeta.part} != path part ${derived.part}`);
+    if (mismatches.chapter) details.push(`chapter metadata ${sourceMeta.chapter} != path chapter ${derived.chapter}`);
+    diagnostics.push(buildStructureDiagnostic(
+      `Path/metadata mismatch for scene "${meta.scene_id}": ${relativePath} (${details.join(", ")}). Using path-derived values.`,
+      {
+        type: "path_metadata_mismatch",
+        sceneId: meta.scene_id ?? null,
+        relativePath,
+      }
+    ));
+  }
+
+  return {
+    universeId: universe_id,
+    projectId: project_id,
+    relativePath,
+    chapterStructure,
+    observedChapter: chapterStructure.chapter
+      ? {
+        chapterId: chapterStructure.chapter.chapter_id,
+        sortIndex: chapterStructure.chapter.sort_index,
+        title: chapterStructure.chapter.title,
+        folderKey: chapterStructure.chapter.folder_key,
+        sourceKind: chapterStructure.chapter.source_kind,
+      }
+      : null,
+    observedEpigraph: chapterStructure.isEpigraph
+      ? {
+        epigraphId: meta.epigraph_id ?? null,
+        chapterId: meta.chapter_id ?? chapterStructure.chapter?.chapter_id ?? null,
+        relativePath,
+      }
+      : null,
+    diagnostics,
+  };
+}
+
+export function buildCanonicalIndexPlan(db, syncDir, file, meta, observedStructure = observeStructureForFile(syncDir, file, { meta })) {
+  const chapterResolution = resolveIndexedChapterForFile(db, {
+    syncDir,
+    projectId: observedStructure.projectId,
+    filePath: file,
+    relativePath: observedStructure.relativePath,
+    meta,
+    chapterStructure: observedStructure.chapterStructure,
+  });
+
+  return {
+    universeId: observedStructure.universeId,
+    projectId: observedStructure.projectId,
+    observedStructure,
+    chapterResolution,
+    canonicalChapter: chapterResolution.upsertChapter,
+    diagnostics: chapterResolution.chapterWarning
+      ? [buildStructureDiagnostic(chapterResolution.chapterWarning)]
+      : [],
+  };
+}
+
+export function readSceneMetadataForSync(syncDir, file, { writable = false } = {}) {
+  return readMeta(file, syncDir, { writable });
+}
+
+export function readSceneFileForSync(syncDir, file, { writable = false } = {}) {
+  const metadataRead = readSceneMetadataForSync(syncDir, file, { writable });
+  const { data: frontmatter, content: prose } = parseFile(file);
+
+  return {
+    ...metadataRead,
+    frontmatter,
+    prose,
+  };
+}
+
+export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructure } = {}) {
+  const canonicalIndexPlan = buildCanonicalIndexPlan(db, syncDir, file, meta, observedStructure);
+  const { universeId: universe_id, projectId: project_id } = canonicalIndexPlan;
+  const { chapterStructure } = canonicalIndexPlan.observedStructure;
   const referenceIds = normalizeReferenceIdList(meta.reference_ids ?? meta.references);
   const explicitSceneLinks = collectExplicitReferenceLinks(
     meta,
@@ -965,22 +1142,13 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     project_id, universe_id ?? null, project_id
   );
 
-  const relativePath = path.relative(syncDir, file);
-  const chapterResolution = resolveIndexedChapterForFile(db, {
-    syncDir,
-    projectId: project_id,
-    filePath: file,
-    relativePath,
-    meta,
-    chapterStructure,
-  });
   const {
     chapterId,
     chapterSortIndex,
     chapterTitle,
     chapterWarning,
     upsertChapter,
-  } = chapterResolution;
+  } = canonicalIndexPlan.chapterResolution;
 
   if (upsertChapter) {
     upsertCanonicalChapterRecord(db, {
@@ -991,7 +1159,7 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
   }
 
   if (chapterStructure.isEpigraph) {
-    return indexCanonicalEpigraph(db, {
+    const result = indexCanonicalEpigraph(db, {
       projectId: project_id,
       chapterId,
       chapterSortIndex,
@@ -999,11 +1167,12 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
       meta,
       prose,
       file,
-      relativePath,
+      relativePath: canonicalIndexPlan.observedStructure.relativePath,
       chapterWarning,
       buildProseChecksum: checksumProse,
       buildDefaultEpigraphId: ({ projectId, chapterId }) => `epi-${slugifyChapterValue(`${projectId}-${chapterId}`)}`,
     });
+    return { ...result, canonicalIndexPlan };
   }
 
   const newChecksum = checksumProse(prose);
@@ -1141,7 +1310,48 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     relation: "informs",
   });
 
-  return { isStale, chapterId, warning: chapterWarning };
+  return { isStale, chapterId, warning: chapterWarning, canonicalIndexPlan };
+}
+
+export function observeOrphanedSidecars(syncDir, { indexedSceneIds = new Set() } = {}) {
+  const diagnostics = [];
+  const sidecars = walkSidecars(syncDir).filter(sidecar => !isNestedMirrorPath(syncDir, sidecar));
+
+  for (const sidecar of sidecars) {
+    const prose = sidecar.replace(/\.meta\.yaml$/, ".md");
+    const proseTxt = sidecar.replace(/\.meta\.yaml$/, ".txt");
+    if (fs.existsSync(prose) || fs.existsSync(proseTxt)) continue;
+
+    let orphanedSceneId = null;
+    try {
+      const raw = fs.readFileSync(sidecar, "utf8");
+      orphanedSceneId = (parseYaml(raw) ?? {}).scene_id ?? null;
+    } catch { /* empty */ }
+
+    const relativePath = path.relative(syncDir, sidecar);
+    if (orphanedSceneId && indexedSceneIds.has(orphanedSceneId)) {
+      diagnostics.push(buildSyncDiagnostic(
+        `Moved scene detected: sidecar for "${orphanedSceneId}" is at stale path ${relativePath} — prose file has moved. Consider relocating the sidecar alongside the prose file.`,
+        {
+          type: "moved_scene",
+          sceneId: orphanedSceneId,
+          relativePath,
+        }
+      ));
+    } else {
+      const label = orphanedSceneId ? `scene "${orphanedSceneId}"` : "unknown scene";
+      diagnostics.push(buildSyncDiagnostic(
+        `Orphaned sidecar (${label}, no matching .md/.txt and not indexed): ${relativePath}`,
+        {
+          type: "orphaned_sidecar",
+          sceneId: orphanedSceneId,
+          relativePath,
+        }
+      ));
+    }
+  }
+
+  return diagnostics;
 }
 
 const WARNING_TYPE_LABELS = {
@@ -1166,7 +1376,7 @@ const WARNING_PATTERNS = [
 
 const MAX_WARNING_EXAMPLES = 5;
 
-function buildWarningSummary(warnings) {
+export function buildWarningSummary(warnings) {
   const summary = {};
   for (const w of warnings) {
     const firstLine = w.split("\n")[0];
@@ -1186,7 +1396,6 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   // (for example after imports or path repairs) are reflected immediately.
   UNIVERSE_PROJECT_ROOT_CACHE.clear();
 
-  const files = walkFiles(syncDir);
   let indexed = 0;
   let staleMarked = 0;
   let epigraphsIndexed = 0;
@@ -1198,69 +1407,43 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
   const seenChapterKeys = new Set();
   const seenEpigraphKeys = new Set();
-  const indexedReferenceDocIds = new Set();
   let sceneIndexFailures = 0;
   const warnings = [];
   const chapterFoldersByProject = new Map();
   const roleFoldersByProject = new Map();
 
-  const scanFiles = [];
-  for (const file of files) {
-    if (isNestedMirrorPath(syncDir, file)) {
-      warnings.push(`Ignored nested mirror path: ${path.relative(syncDir, file)}`);
-      continue;
-    }
-    scanFiles.push(file);
+  const syncScan = scanSyncFiles(syncDir);
+  const scanFiles = syncScan.files;
+  for (const diagnostic of syncScan.diagnostics) {
+    warnings.push(diagnostic.message);
   }
 
   // --- Pass 1: world files and reference docs (characters/places must be indexed
   // before scenes so that character name -> ID resolution in scene_characters works) ---
-  for (const file of scanFiles) {
-    if (isReferenceFile(syncDir, file)) {
-      try {
-        const { data, content } = parseFile(file);
-        const docId = indexReferenceFile(db, syncDir, file, data, content);
-        indexedReferenceDocIds.add(docId);
-      } catch (err) {
-        process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
-      }
-      continue;
-    }
-
-    if (!isWorldFile(syncDir, file)) continue;
-    try {
-      const { meta } = readMeta(file, syncDir, { writable });
-      if (!Object.keys(meta).length) {
-        const { data } = parseFile(file);
-        indexWorldFile(db, syncDir, file, data);
-      } else {
-        indexWorldFile(db, syncDir, file, meta);
-      }
-    } catch (err) {
-      process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
-    }
-  }
-
-  if (canPruneReferenceDocs(syncDir)) {
-    pruneMissingReferenceDocs(db, indexedReferenceDocIds);
-  }
+  regenerateReferenceAndWorldIndexes(db, syncDir, scanFiles, { writable, pruneReferenceDocs: true });
 
   // --- Pass 2: scene files ---
   for (const file of scanFiles) {
     if (isWorldFile(syncDir, file) || isReferenceFile(syncDir, file)) continue;
     try {
-      const { meta, sourceMeta, sidecarGenerated, derived, mismatches } = readMeta(file, syncDir, { writable });
+      const { meta, sourceMeta, sidecarGenerated, derived, mismatches } = readSceneMetadataForSync(syncDir, file, { writable });
       if (sidecarGenerated) sidecarsMigrated++;
-      const chapterStructure = inferChapterStructureFromPath(syncDir, file, meta);
+      const structureObservation = observeStructureForFile(syncDir, file, {
+        meta,
+        sourceMeta,
+        derived,
+        mismatches,
+      });
+      const { chapterStructure } = structureObservation;
 
       if (!meta.scene_id && !chapterStructure.isEpigraph) {
         skipped++;
-        if (!quiet) warnings.push(`Skipped (no scene_id): ${path.relative(syncDir, file)}`);
+        if (!quiet) warnings.push(`Skipped (no scene_id): ${structureObservation.relativePath}`);
         continue;
       }
 
       // Duplicate scene_id detection
-      const { project_id } = inferProjectAndUniverse(syncDir, file);
+      const project_id = structureObservation.projectId;
       const key = `${meta.scene_id}::${project_id}`;
       if (meta.scene_id && seenSceneIds.has(key)) {
         warnings.push(
@@ -1284,18 +1467,17 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
         }
       }
 
-      if (mismatches.part || mismatches.chapter) {
-        const details = [];
-        if (mismatches.part) details.push(`part metadata ${sourceMeta.part} != path part ${derived.part}`);
-        if (mismatches.chapter) details.push(`chapter metadata ${sourceMeta.chapter} != path chapter ${derived.chapter}`);
-        warnings.push(
-          `Path/metadata mismatch for scene "${meta.scene_id}": ${path.relative(syncDir, file)} (${details.join(", ")}). Using path-derived values.`
-        );
+      for (const diagnostic of structureObservation.diagnostics) {
+        warnings.push(diagnostic.message);
       }
 
-      const { data: _frontmatter, content: prose } = parseFile(file);
-      const result = indexSceneFile(db, syncDir, file, meta, prose);
-      if (result.warning) {
+      const { content: prose } = parseFile(file);
+
+      const result = indexSceneFile(db, syncDir, file, meta, prose, { observedStructure: structureObservation });
+      const canonicalDiagnostics = result.canonicalIndexPlan?.diagnostics ?? [];
+      if (canonicalDiagnostics.length) {
+        for (const diagnostic of canonicalDiagnostics) warnings.push(diagnostic.message);
+      } else if (result.warning) {
         warnings.push(result.warning);
       }
       if (result.chapterId) {
@@ -1337,35 +1519,16 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     }
   }
 
-  if (canPruneScenes(syncDir) && sceneIndexFailures === 0) {
-    pruneMissingScenes(db, seenSceneKeys, syncDir);
-    pruneMissingEpigraphs(db, seenEpigraphKeys, syncDir);
-    pruneMissingChapters(db, seenChapterKeys, syncDir);
-  }
+  pruneSyncDerivedIndexes(db, syncDir, {
+    seenSceneKeys,
+    seenEpigraphKeys,
+    seenChapterKeys,
+    sceneIndexFailures,
+  });
 
   // --- Orphaned sidecar detection ---
-  const sidecars = walkSidecars(syncDir).filter(sidecar => !isNestedMirrorPath(syncDir, sidecar));
-  for (const sidecar of sidecars) {
-    const prose = sidecar.replace(/\.meta\.yaml$/, ".md");
-    const proseTxt = sidecar.replace(/\.meta\.yaml$/, ".txt");
-    if (!fs.existsSync(prose) && !fs.existsSync(proseTxt)) {
-      let orphanedSceneId = null;
-      try {
-        const raw = fs.readFileSync(sidecar, "utf8");
-        orphanedSceneId = (parseYaml(raw) ?? {}).scene_id ?? null;
-      } catch { /* empty */ }
-
-      if (orphanedSceneId && indexedSceneIds.has(orphanedSceneId)) {
-        warnings.push(
-          `Moved scene detected: sidecar for "${orphanedSceneId}" is at stale path ${path.relative(syncDir, sidecar)} — prose file has moved. Consider relocating the sidecar alongside the prose file.`
-        );
-      } else {
-        const label = orphanedSceneId ? `scene "${orphanedSceneId}"` : "unknown scene";
-        warnings.push(
-          `Orphaned sidecar (${label}, no matching .md/.txt and not indexed): ${path.relative(syncDir, sidecar)}`
-        );
-      }
-    }
+  for (const diagnostic of observeOrphanedSidecars(syncDir, { indexedSceneIds })) {
+    warnings.push(diagnostic.message);
   }
 
   const warningSummary = buildWarningSummary(warnings);

package/src/tools/sync.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import { syncAll, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { importScrivenerSync, validateProjectId } from "../sync/importer.js";
+import { runStructureDiagnostics } from "../structure/structure-diagnostics.js";
 
 export function registerSyncTools(s, {
   db,
@@ -45,6 +46,27 @@ export function registerSyncTools(s, {
     return { content: [{ type: "text", text: parts.join(" ") }] };
   });
 
+  s.tool(
+    "diagnose_structure",
+    "Run read-only structure diagnostics against the current index and sync files. Reports canonical drift, ambiguous folder-derived structure, unknown chapter links, epigraph conflicts, and compatibility chapter mismatches without repairing files or mutating the database.",
+    {
+      project_id: z.string().optional().describe("Optional project ID to limit diagnostics to one project."),
+    },
+    async ({ project_id } = {}) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      return jsonResponse(runStructureDiagnostics(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id ?? null,
+      }));
+    }
+  );
+
   s.tool(
     "import_scrivener_sync",
     "[STABLE] Import Scrivener External Folder Sync Draft files into this server's WRITING_SYNC_DIR by generating scene sidecars and reconciling by Scrivener binder ID. This is the recommended default path for first-time setup before sync().",

package/src/workflows/workflow-catalogue.js

@@ -69,6 +69,7 @@ export const WORKFLOW_CATALOGUE = [
     use_when: "Use when new material has been added, sync/import reveals metadata gaps, or normal work touches scenes or documents with weak, stale, or missing metadata support.",
     steps: [
       { tool: "sync", note: "Refresh the index and use the result as the main signal that material has changed or parity may need attention." },
+      { tool: "diagnose_structure", note: "Use when sync warning summaries suggest chapter, epigraph, or folder-derived structure drift that should be understood before repair." },
       { tool: "enrich_scene", note: "Use for lightweight opportunistic recovery when the current task is already touching a specific low-parity scene." },
       { tool: "enrich_scene_characters_batch", note: "Use when recovery scope is broad enough to justify focused catch-up work; prefer dry_run first." },
       { tool: "suggest_scene_references", note: "Use when low parity is specifically about missing scene-to-reference relationships." },
@@ -90,6 +91,7 @@ export const WORKFLOW_CATALOGUE = [
     steps: [
       { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
       { tool: "sync", note: "Index scenes from disk so the main manuscript workflows can operate." },
+      { tool: "diagnose_structure", note: "Run after sync when connecting existing projects to inspect structure drift without repairing anything." },
     ],
   },
   {