@hanna84/mcp-writing 3.22.5 → 3.23.1

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.23.1](https://github.com/hannasdev/mcp-writing/compare/v3.23.0...v3.23.1)
+
+- fix: align relationship compatibility sync and audit [`#231`](https://github.com/hannasdev/mcp-writing/pull/231)
+
+#### [v3.23.0](https://github.com/hannasdev/mcp-writing/compare/v3.22.5...v3.23.0)
+
+> 30 May 2026
+
+- feat: guard scene relationship metadata updates [`#230`](https://github.com/hannasdev/mcp-writing/pull/230)
+- Release 3.23.0 [`93c359f`](https://github.com/hannasdev/mcp-writing/commit/93c359f71dde69afed34e7b024aa21729810df2b)
+
 #### [v3.22.5](https://github.com/hannasdev/mcp-writing/compare/v3.22.4...v3.22.5)
 
+> 30 May 2026
+
 - chore(deps): Bump qs in the npm_and_yarn group across 1 directory [`#214`](https://github.com/hannasdev/mcp-writing/pull/214)
+- Release 3.22.5 [`a4146a0`](https://github.com/hannasdev/mcp-writing/commit/a4146a03a9976d022afb75842bee3ce50742fe65)
 
 #### [v3.22.4](https://github.com/hannasdev/mcp-writing/compare/v3.22.3...v3.22.4)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.22.5",
+  "version": "3.23.1",
   "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/sync/scene-character-batch.js

@@ -57,6 +57,16 @@ function resolveCharacterEntry(entry, characterRows) {
   return resolveCharacterReference(entry, characterRows);
 }
 
+function normalizeCompatibilityCharacters(value) {
+  const rawValues = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value.split(",")
+      : [];
+
+  return [...new Set(rawValues.map(String).map(character => character.trim()).filter(Boolean))];
+}
+
 function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {
   const kept = new Set(characterIds);
 
@@ -140,7 +150,7 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
       const { content: prose } = matter(raw);
       const { sourceMeta: meta } = readSourceMeta(scene.file_path, syncDir, { writable: !dry_run });
 
-      const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
+      const before_characters = normalizeCompatibilityCharacters(meta.characters);
       const normalized_before_characters = [...new Set(
         before_characters
           .map(character => resolveCharacterEntry(character, normalizedCharacterRows))

package/src/sync/sync.js

@@ -299,6 +299,24 @@ export function normalizeReferenceIdList(values) {
   )];
 }
 
+function normalizeMetadataList(values) {
+  const rawValues = Array.isArray(values)
+    ? values
+    : typeof values === "string"
+      ? values.split(",")
+      : [];
+
+  return [...new Set(
+    rawValues
+      .map(value => String(value).trim())
+      .filter(Boolean)
+  )];
+}
+
+function isVersionContinuityMarker(value) {
+  return /^v\d[\d.a-z]*$/i.test(String(value).trim());
+}
+
 function normalizeReferenceRelation(value, fallbackRelation) {
   const normalized = String(value ?? fallbackRelation ?? "").trim().toLowerCase();
   if (/^[a-z][a-z0-9_-]*$/.test(normalized)) return normalized;
@@ -1272,7 +1290,131 @@ export function readSceneFileForSync(syncDir, file, { writable = false } = {}) {
   };
 }
 
-export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructure, managedStructure = false } = {}) {
+export function resolveSceneCharacterCompatibilityId(db, value) {
+  let characterId = value;
+  if (!/^char-/.test(value)) {
+    let row = db.prepare(`SELECT character_id FROM characters WHERE lower(name) = lower(?)`).get(value);
+    if (!row) {
+      const words = value.toLowerCase().split(/\s+/).filter(Boolean);
+      const all = db.prepare(`SELECT character_id, name FROM characters`).all();
+      const match = all.find(r =>
+        words.every(w => r.name.toLowerCase().includes(w))
+      );
+      if (match) row = match;
+    }
+    if (row) characterId = row.character_id;
+  }
+  return characterId;
+}
+
+function querySceneRelationshipIds(db, { sceneId, projectId, table, idColumn }) {
+  return db.prepare(`
+    SELECT ${idColumn} AS id
+    FROM ${table}
+    WHERE scene_id = ? AND project_id = ?
+    ORDER BY ${idColumn}
+  `).all(sceneId, projectId).map((row) => row.id);
+}
+
+function sameStringSet(a, b) {
+  const left = [...new Set(a.map(String))].sort();
+  const right = [...new Set(b.map(String))].sort();
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function selectRelationshipIndexValues({ sceneId, projectId, relationshipKind, existing, compatibility, compatibilityMode, hasCompatibilityField, hasExistingScene }) {
+  if (!hasCompatibilityField) {
+    return {
+      values: existing,
+      diagnostic: null,
+    };
+  }
+  if (compatibilityMode === "adopt_compatibility") {
+    return {
+      values: compatibility,
+      diagnostic: null,
+    };
+  }
+  if (hasExistingScene && !sameStringSet(existing, compatibility)) {
+    return {
+      values: existing,
+      diagnostic: {
+        type: "relationship_compatibility_drift",
+        relationship_kind: relationshipKind,
+        scene_id: sceneId,
+        project_id: projectId,
+        canonical_values: existing,
+        compatibility_values: compatibility,
+        message: `Relationship compatibility drift for scene "${sceneId}" in project "${projectId}": sidecar ${relationshipKind} differ from SQLite ${relationshipKind}; preserved SQLite relationship rows. Run audit_relationship_metadata before applying an outcome-level repair.`,
+      },
+    };
+  }
+  return {
+    values: compatibility,
+    diagnostic: null,
+  };
+}
+
+function relationshipCompatibilityFieldsFromMeta(meta = {}) {
+  return {
+    characters: Object.hasOwn(meta, "characters"),
+    places: Object.hasOwn(meta, "places"),
+  };
+}
+
+function buildSceneRelationshipIndexPlan(db, { meta, projectId, compatibilityMode = "preserve_existing", compatibilityFields = relationshipCompatibilityFieldsFromMeta(meta), hasExistingScene = false }) {
+  const compatibilityCharacters = [];
+  const compatibilityVersionMarkers = [];
+  for (const value of normalizeMetadataList(meta.characters)) {
+    if (isVersionContinuityMarker(value)) {
+      compatibilityVersionMarkers.push(value);
+      continue;
+    }
+    compatibilityCharacters.push(resolveSceneCharacterCompatibilityId(db, value));
+  }
+  const compatibilityPlaces = normalizeMetadataList(meta.places);
+  const existingCharacters = querySceneRelationshipIds(db, {
+    sceneId: meta.scene_id,
+    projectId,
+    table: "scene_characters",
+    idColumn: "character_id",
+  });
+  const existingPlaces = querySceneRelationshipIds(db, {
+    sceneId: meta.scene_id,
+    projectId,
+    table: "scene_places",
+    idColumn: "place_id",
+  });
+  const characterSelection = selectRelationshipIndexValues({
+    sceneId: meta.scene_id,
+    projectId,
+    relationshipKind: "characters",
+    existing: existingCharacters,
+    compatibility: compatibilityCharacters,
+    compatibilityMode,
+    hasCompatibilityField: compatibilityFields.characters,
+    hasExistingScene,
+  });
+  const placeSelection = selectRelationshipIndexValues({
+    sceneId: meta.scene_id,
+    projectId,
+    relationshipKind: "places",
+    existing: existingPlaces,
+    compatibility: compatibilityPlaces,
+    compatibilityMode,
+    hasCompatibilityField: compatibilityFields.places,
+    hasExistingScene,
+  });
+
+  return {
+    characters: characterSelection.values,
+    places: placeSelection.values,
+    compatibilityVersionMarkers,
+    diagnostics: [characterSelection.diagnostic, placeSelection.diagnostic].filter(Boolean),
+  };
+}
+
+export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructure, managedStructure = false, relationshipCompatibilityMode = "preserve_existing", relationshipCompatibilityFields } = {}) {
   const canonicalIndexPlan = buildCanonicalIndexPlan(db, syncDir, file, meta, observedStructure, { managedStructure });
   const { universeId: universe_id, projectId: project_id } = canonicalIndexPlan;
   const { chapterStructure } = canonicalIndexPlan.observedStructure;
@@ -1408,58 +1550,44 @@ export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructu
     new Date().toISOString()
   );
 
+  const relationshipIndexPlan = buildSceneRelationshipIndexPlan(db, {
+    meta,
+    projectId: project_id,
+    compatibilityMode: relationshipCompatibilityMode,
+    compatibilityFields: relationshipCompatibilityFields,
+    hasExistingScene: Boolean(existing),
+  });
+  const tagValues = [
+    ...normalizeMetadataList(meta.tags),
+    ...relationshipIndexPlan.compatibilityVersionMarkers,
+    ...normalizeMetadataList(meta.versions),
+  ];
+
   db.prepare(`DELETE FROM scene_characters WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
   db.prepare(`DELETE FROM scene_places WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
   db.prepare(`DELETE FROM scene_tags WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
+  db.prepare(`DELETE FROM scenes_fts WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
 
-  for (const c of (meta.characters ?? [])) {
-    // Version continuity markers (e.g. v7.3, v3.3b) are tracked as tags, not characters
-    if (/^v\d[\d.a-z]*$/i.test(c)) {
-      db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(meta.scene_id, project_id, c);
-      continue;
-    }
-    let cid = c;
-    // If the value looks like a name rather than an ID, try to resolve it
-    if (!/^char-/.test(c)) {
-      // 1. Exact name match (case-insensitive)
-      let row = db.prepare(`SELECT character_id FROM characters WHERE lower(name) = lower(?)`).get(c);
-      // 2. Word-overlap: all words in the keyword appear in the stored name
-      //    Handles "Victor Sidorin" → "Victor Alexeyvich Sidorin"
-      if (!row) {
-        const words = c.toLowerCase().split(/\s+/).filter(Boolean);
-        const all = db.prepare(`SELECT character_id, name FROM characters`).all();
-        const match = all.find(r =>
-          words.every(w => r.name.toLowerCase().includes(w))
-        );
-        if (match) row = match;
-      }
-      if (row) cid = row.character_id;
-    }
+  for (const cid of relationshipIndexPlan.characters) {
     db.prepare(`INSERT OR IGNORE INTO scene_characters (scene_id, project_id, character_id) VALUES (?, ?, ?)`).run(
       meta.scene_id, project_id, cid
     );
   }
-  for (const p of (meta.places ?? [])) {
+  for (const p of relationshipIndexPlan.places) {
     db.prepare(`INSERT OR IGNORE INTO scene_places (scene_id, project_id, place_id) VALUES (?, ?, ?)`).run(
       meta.scene_id, project_id, p
     );
   }
-  for (const t of (meta.tags ?? [])) {
+  for (const t of tagValues) {
     db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(
       meta.scene_id, project_id, t
     );
   }
-  for (const v of (meta.versions ?? [])) {
-    db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(
-      meta.scene_id, project_id, v
-    );
-  }
 
   const keywordTokens = [
-    ...(meta.tags ?? []),
-    ...(meta.characters ?? []),
-    ...(meta.places ?? []),
-    ...(meta.versions ?? []),
+    ...tagValues,
+    ...relationshipIndexPlan.characters,
+    ...relationshipIndexPlan.places,
   ]
     .filter(Boolean)
     .map(String)
@@ -1467,7 +1595,7 @@ export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructu
     .filter(Boolean)
     .join(" ");
 
-  db.prepare(`INSERT OR REPLACE INTO scenes_fts (scene_id, project_id, logline, title, keywords) VALUES (?, ?, ?, ?, ?)`).run(
+  db.prepare(`INSERT INTO scenes_fts (scene_id, project_id, logline, title, keywords) VALUES (?, ?, ?, ?, ?)`).run(
     meta.scene_id,
     project_id,
     meta.logline ?? meta.synopsis ?? "",
@@ -1493,7 +1621,13 @@ export function indexSceneFile(db, syncDir, file, meta, prose, { observedStructu
     relation: "informs",
   });
 
-  return { isStale, chapterId, warning: chapterWarning, canonicalIndexPlan };
+  return {
+    isStale,
+    chapterId,
+    warning: chapterWarning,
+    canonicalIndexPlan,
+    relationshipCompatibilityDiagnostics: relationshipIndexPlan.diagnostics,
+  };
 }
 
 export function isManagedStructureProject(db, projectId) {
@@ -1564,6 +1698,7 @@ const WARNING_TYPE_LABELS = {
   unobserved_canonical_scene: "Unobserved canonical scene",
   missing_canonical_chapter: "Missing canonical chapter",
   missing_canonical_epigraph: "Missing canonical epigraph",
+  relationship_compatibility_drift: "Relationship compatibility drift",
   nested_mirror: "Ignored nested mirror path",
 };
 
@@ -1578,6 +1713,7 @@ const WARNING_PATTERNS = [
   { type: "unobserved_canonical_scene", re: /^Managed sync preserved canonical scene not observed during sync scan:/ },
   { type: "missing_canonical_chapter", re: /^Managed sync preserved canonical chapter missing from filesystem:/ },
   { type: "missing_canonical_epigraph", re: /^Managed sync preserved canonical epigraph missing from filesystem:/ },
+  { type: "relationship_compatibility_drift", re: /^Relationship compatibility drift/ },
   { type: "nested_mirror",          re: /^Ignored nested mirror path:/ },
 ];
 
@@ -1598,7 +1734,7 @@ export function buildWarningSummary(warnings) {
   return summary;
 }
 
-export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
+export function syncAll(db, syncDir, { quiet = false, writable = false, relationshipCompatibilityMode = "preserve_existing" } = {}) {
   // Reset per-run inference cache so filesystem changes between sync calls
   // (for example after imports or path repairs) are reflected immediately.
   UNIVERSE_PROJECT_ROOT_CACHE.clear();
@@ -1701,6 +1837,8 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       const result = indexSceneFile(db, syncDir, file, meta, prose, {
         observedStructure: structureObservation,
         managedStructure: managedProjectIds.has(project_id),
+        relationshipCompatibilityMode,
+        relationshipCompatibilityFields: relationshipCompatibilityFieldsFromMeta(sourceMeta),
       });
       const canonicalDiagnostics = result.canonicalIndexPlan?.diagnostics ?? [];
       if (canonicalDiagnostics.length) {
@@ -1708,6 +1846,9 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       } else if (result.warning) {
         warnings.push(result.warning);
       }
+      for (const diagnostic of result.relationshipCompatibilityDiagnostics ?? []) {
+        warnings.push(diagnostic.message);
+      }
       if (result.chapterId) {
         const chapterKey = `${result.chapterId}::${project_id}`;
         seenChapterKeys.add(chapterKey);

package/src/tools/metadata.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { readMeta, readSourceMeta, writeMeta, indexSceneFile, isManagedStructureProject, normalizeSceneMetaForPath } from "../sync/sync.js";
+import { readMeta, readSourceMeta, writeMeta, indexSceneFile, isManagedStructureProject, normalizeSceneMetaForPath, resolveSceneCharacterCompatibilityId } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
 import {
@@ -34,6 +34,7 @@ import {
 } from "../structure/project-backup-refresh.js";
 
 const STRUCTURAL_SCENE_METADATA_FIELDS = ["part", "chapter", "chapter_id", "chapter_title", "timeline_position"];
+const RELATIONSHIP_SCENE_METADATA_FIELDS = ["characters", "places"];
 
 function emptyBackupMutationResult() {
   return {
@@ -108,6 +109,22 @@ function getProvidedStructuralSceneMetadataFields(fields) {
   return STRUCTURAL_SCENE_METADATA_FIELDS.filter((field) => Object.hasOwn(fields, field));
 }
 
+function getProvidedRelationshipSceneMetadataFields(fields) {
+  return RELATIONSHIP_SCENE_METADATA_FIELDS.filter((field) => Object.hasOwn(fields, field));
+}
+
+function buildRelationshipMetadataBoundaryDetails({ projectId, sceneId, blockedFields }) {
+  return {
+    project_id: projectId,
+    scene_id: sceneId,
+    blocked_fields: blockedFields,
+    boundary: "scene_relationship_metadata",
+    relationship_tools: ["connect_character_place_evidence", "audit_relationship_metadata"],
+    discovery_workflows: ["describe_workflows", "find_scenes", "list_characters", "list_places"],
+    next_step: "Use find_scenes, list_characters, and list_places to identify stable IDs. Use connect_character_place_evidence only when the scene proves paired sheet-backed character/place evidence; use audit_relationship_metadata to review legacy sidecar/frontmatter relationship fields. Character-only or place-only scene evidence is not changed through update_scene_metadata.",
+  };
+}
+
 function persistReferenceDocLink({ filePath, syncDir, targetDocId, relation }) {
   const syncDirAbs = path.resolve(syncDir);
   const syncDirReal = resolveBoundaryRootReal(syncDirAbs);
@@ -437,6 +454,85 @@ function querySceneRelationshipSnapshot(db, { sceneId, projectId }) {
   };
 }
 
+function sameStringSet(a, b) {
+  const left = [...new Set(a.map(String))].sort();
+  const right = [...new Set(b.map(String))].sort();
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function normalizeSceneRelationshipCompatibilityFields(db, sourceMeta) {
+  const hasCharactersField = Object.hasOwn(sourceMeta, "characters");
+  const hasPlacesField = Object.hasOwn(sourceMeta, "places");
+  return {
+    has_relationship_fields: hasCharactersField || hasPlacesField,
+    has_characters_field: hasCharactersField,
+    has_places_field: hasPlacesField,
+    characters: normalizeStringList(sourceMeta.characters)
+      .filter((value) => !isVersionContinuityMarker(value))
+      .map((value) => resolveSceneCharacterCompatibilityId(db, value)),
+    places: normalizeStringList(sourceMeta.places),
+  };
+}
+
+function sceneRelationshipCompatibilityHasDrift(canonicalRelationships, compatibilityRelationships) {
+  return (
+    compatibilityRelationships.has_characters_field &&
+    !sameStringSet(canonicalRelationships.characters, compatibilityRelationships.characters)
+  ) || (
+    compatibilityRelationships.has_places_field &&
+    !sameStringSet(canonicalRelationships.places, compatibilityRelationships.places)
+  );
+}
+
+function restoreSceneRelationshipSnapshot(db, { sceneId, projectId, snapshot }) {
+  db.prepare(`DELETE FROM scene_characters WHERE scene_id = ? AND project_id = ?`).run(sceneId, projectId);
+  db.prepare(`DELETE FROM scene_places WHERE scene_id = ? AND project_id = ?`).run(sceneId, projectId);
+
+  const insertCharacter = db.prepare(`
+    INSERT OR IGNORE INTO scene_characters (scene_id, project_id, character_id)
+    VALUES (?, ?, ?)
+  `);
+  for (const characterId of snapshot.characters) {
+    insertCharacter.run(sceneId, projectId, characterId);
+  }
+
+  const insertPlace = db.prepare(`
+    INSERT OR IGNORE INTO scene_places (scene_id, project_id, place_id)
+    VALUES (?, ?, ?)
+  `);
+  for (const placeId of snapshot.places) {
+    insertPlace.run(sceneId, projectId, placeId);
+  }
+}
+
+function isVersionContinuityMarker(value) {
+  return /^v\d[\d.a-z]*$/i.test(String(value).trim());
+}
+
+function buildSceneMetadataSearchKeywords(meta, relationshipSnapshot) {
+  const compatibilityVersionMarkers = normalizeStringList(meta.characters).filter(isVersionContinuityMarker);
+  return [
+    ...normalizeStringList(meta.tags),
+    ...compatibilityVersionMarkers,
+    ...relationshipSnapshot.characters,
+    ...relationshipSnapshot.places,
+    ...normalizeStringList(meta.versions),
+  ]
+    .filter(Boolean)
+    .map(String)
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .join(" ");
+}
+
+function restoreSceneRelationshipSearchKeywords(db, { sceneId, projectId, meta, snapshot }) {
+  db.prepare(`
+    UPDATE scenes_fts
+    SET keywords = ?
+    WHERE scene_id = ? AND project_id = ?
+  `).run(buildSceneMetadataSearchKeywords(meta, snapshot), sceneId, projectId);
+}
+
 export function registerMetadataTools(s, {
   db,
   SYNC_DIR,
@@ -995,6 +1091,39 @@ export function registerMetadataTools(s, {
       }
       try {
         const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: false });
+        const compatibilityRelationships = normalizeSceneRelationshipCompatibilityFields(db, sourceMeta);
+        if (compatibilityRelationships.has_relationship_fields) {
+          const canonicalRelationships = querySceneRelationshipSnapshot(db, {
+            sceneId: scene.scene_id,
+            projectId: scene.project_id,
+          });
+          diagnostics.push({
+            type: "scene_relationship_compatibility_input",
+            severity: "info",
+            message: `Scene '${scene.scene_id}' retains sidecar/frontmatter character/place relationship fields as compatibility input; SQLite scene relationship rows remain canonical.`,
+            scene_id: scene.scene_id,
+            project_id: scene.project_id,
+            compatibility: compatibilityRelationships,
+            canonical: canonicalRelationships,
+            authority: {
+              canonical_owner: "SQLite scene_characters/scene_places",
+              compatibility_mutation_surface: false,
+            },
+            next_step: "Use this as migration or review evidence only. Use outcome-level relationship tools for current repairs.",
+          });
+          if (sceneRelationshipCompatibilityHasDrift(canonicalRelationships, compatibilityRelationships)) {
+            diagnostics.push({
+              type: "scene_relationship_compatibility_drift",
+              severity: "warning",
+              message: `Scene '${scene.scene_id}' sidecar/frontmatter relationship fields disagree with canonical SQLite relationship rows.`,
+              scene_id: scene.scene_id,
+              project_id: scene.project_id,
+              compatibility: compatibilityRelationships,
+              canonical: canonicalRelationships,
+              next_step: "Treat SQLite relationship rows as canonical. Use find_scenes, list_characters, and list_places to inspect stable IDs; use connect_character_place_evidence for paired sheet-backed evidence or leave character-only/place-only repairs to a deliberately named future workflow.",
+            });
+          }
+        }
         if (sourceMeta.threads) {
           diagnostics.push({
             type: "sidecar_threads_compatibility_input",
@@ -1080,6 +1209,7 @@ export function registerMetadataTools(s, {
       summary: {
         diagnostics_count: diagnostics.length,
         stale_scene_count: diagnostics.filter(diagnostic => diagnostic.type === "stale_scene_relationship_index").length,
+        compatibility_drift_count: diagnostics.filter(diagnostic => diagnostic.type === "scene_relationship_compatibility_drift").length,
         compatibility_note_count: diagnostics.filter(diagnostic => diagnostic.severity === "info").length,
       },
       next_steps: [
@@ -2214,7 +2344,7 @@ export function registerMetadataTools(s, {
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",
-    "Update one or more non-structural metadata fields for a scene. Writes only supplied non-structural fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose or mirrors path-derived structure. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Changes are immediately reflected in the index. Only available when the sync dir is writable.",
+    "Update one or more non-structural, non-relationship metadata fields for a scene. Writes only supplied allowed fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose, mirrors path-derived structure, or changes scene character/place relationship authority. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Relationship fields (characters, places) are rejected here; use discovery workflows plus connect_character_place_evidence for paired sheet-backed character/place evidence, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Allowed changes are immediately reflected in the index. Only available when the sync dir is writable.",
     {
       scene_id:   z.string().describe("The scene_id to update (e.g. 'sc-011-sebastian')."),
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
@@ -2231,8 +2361,8 @@ export function registerMetadataTools(s, {
         timeline_position: z.number().int().optional().describe("Rejected by update_scene_metadata. Use move_scene for ordering changes."),
         story_time:        z.string().optional(),
         tags:              z.array(z.string()).optional(),
-        characters:        z.array(z.string()).optional(),
-        places:            z.array(z.string()).optional(),
+        characters:        z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence for paired sheet-backed evidence, and audit_relationship_metadata for compatibility review."),
+        places:            z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence for paired sheet-backed evidence, and audit_relationship_metadata for compatibility review."),
       }).describe("Fields to update. Only supplied keys are changed."),
     },
     async ({ scene_id, project_id, fields }) => {
@@ -2244,6 +2374,18 @@ export function registerMetadataTools(s, {
       if (!scene) {
         return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
       }
+      const relationshipFields = getProvidedRelationshipSceneMetadataFields(fields);
+      if (relationshipFields.length > 0) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          "update_scene_metadata cannot change relationship-boundary fields characters or places. Scene relationship metadata is sheet-backed and must use outcome-level relationship workflows, not generic sidecar metadata writes.",
+          buildRelationshipMetadataBoundaryDetails({
+            projectId: project_id,
+            sceneId: scene_id,
+            blockedFields: relationshipFields,
+          })
+        );
+      }
       const structuralFields = getProvidedStructuralSceneMetadataFields(fields);
       if (structuralFields.length > 0) {
         return errorResponse(
@@ -2258,6 +2400,7 @@ export function registerMetadataTools(s, {
         );
       }
       try {
+        const relationshipSnapshot = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
         const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
         const updated = { ...sourceMeta, ...fields };
         writeMeta(scene.file_path, updated, { syncDir: SYNC_DIR });
@@ -2267,6 +2410,17 @@ export function registerMetadataTools(s, {
         indexSceneFile(db, SYNC_DIR, scene.file_path, normalizedUpdated, prose, {
           managedStructure: isManagedStructureProject(db, project_id),
         });
+        restoreSceneRelationshipSnapshot(db, {
+          sceneId: scene_id,
+          projectId: project_id,
+          snapshot: relationshipSnapshot,
+        });
+        restoreSceneRelationshipSearchKeywords(db, {
+          sceneId: scene_id,
+          projectId: project_id,
+          meta: normalizedUpdated,
+          snapshot: relationshipSnapshot,
+        });
         const backupResult = refreshProjectScopedBackupAfterMutation(db, {
           syncDir: SYNC_DIR,
           projectId: project_id,

package/src/tools/sync.js

@@ -470,7 +470,10 @@ export function registerSyncTools(s, {
 
       let syncResult = null;
       if (!dry_run && !preflight && auto_sync) {
-        syncResult = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+        syncResult = syncAll(db, SYNC_DIR, {
+          writable: SYNC_DIR_WRITABLE,
+          relationshipCompatibilityMode: "adopt_compatibility",
+        });
       }
 
       return jsonResponse({
@@ -572,7 +575,10 @@ export function registerSyncTools(s, {
         },
         onComplete: (completedJob) => {
           if (!auto_sync || dry_run || preflight || completedJob.status !== "completed") return;
-          const syncResult = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+          const syncResult = syncAll(db, SYNC_DIR, {
+            writable: SYNC_DIR_WRITABLE,
+            relationshipCompatibilityMode: "adopt_compatibility",
+          });
           if (completedJob.result && completedJob.result.ok) {
             completedJob.result.sync = {
               indexed: syncResult.indexed,
@@ -652,7 +658,10 @@ export function registerSyncTools(s, {
         },
         onComplete: (completedJob) => {
           if (!auto_sync || dry_run || completedJob.status !== "completed") return;
-          const syncResult = syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+          const syncResult = syncAll(db, SYNC_DIR, {
+            writable: SYNC_DIR_WRITABLE,
+            relationshipCompatibilityMode: "adopt_compatibility",
+          });
           if (completedJob.result && completedJob.result.ok) {
             completedJob.result.sync = {
               indexed: syncResult.indexed,
@@ -776,7 +785,10 @@ export function registerSyncTools(s, {
         onComplete: (completedJob) => {
           if (dry_run || completedJob.status !== "completed" || !completedJob.result?.ok) return;
 
-          syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+          syncAll(db, SYNC_DIR, {
+            writable: SYNC_DIR_WRITABLE,
+            relationshipCompatibilityMode: "adopt_compatibility",
+          });
 
           const changedScenes = (completedJob.result.results ?? [])
             .filter(row => row.status === "changed")
@@ -980,6 +992,7 @@ export function registerSyncTools(s, {
         writeMeta(scene.file_path, sourceUpdatedMeta, { syncDir: SYNC_DIR });
         indexSceneFile(db, SYNC_DIR, scene.file_path, updatedMeta, prose, {
           managedStructure: isManagedStructureProject(db, scene.project_id),
+          relationshipCompatibilityMode: "adopt_compatibility",
         });
         db.prepare(`UPDATE scenes SET metadata_stale = 0 WHERE scene_id = ? AND project_id = ?`)
           .run(scene.scene_id, scene.project_id);