@hanna84/mcp-writing 3.23.0 → 3.23.2

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.2](https://github.com/hannasdev/mcp-writing/compare/v3.23.1...v3.23.2)
+
+- docs: clarify relationship workflow guidance [`#232`](https://github.com/hannasdev/mcp-writing/pull/232)
+
+#### [v3.23.1](https://github.com/hannasdev/mcp-writing/compare/v3.23.0...v3.23.1)
+
+> 30 May 2026
+
+- fix: align relationship compatibility sync and audit [`#231`](https://github.com/hannasdev/mcp-writing/pull/231)
+- Release 3.23.1 [`f0b643b`](https://github.com/hannasdev/mcp-writing/commit/f0b643bcb7b09adf066380d37718b09001dd3020)
+
 #### [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)
 

package/README.md

@@ -30,7 +30,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 - **Core platform complete:** Metadata-first analysis, SQLite-canonical structural and relationship metadata, compatibility sidecar maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
 - **Recently completed:** Database Backup and Recovery added project backup export, freshness diagnostics, advisory operation history, automatic backup refresh after sanctioned project-scoped canonical mutations, dry-run restore planning, transactional restore application, and backup/restore operations guidance.
 - **Previous milestone:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
-- **Active development:** Architecture Alignment Follow-up M5, documenting sidecar compatibility, migration, and deprecation expectations.
+- **Active development:** Relationship Metadata Boundary M3, aligning workflow and generated documentation around SQLite-canonical relationship authority.
 - **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 
@@ -153,7 +153,7 @@ Outcome: subplot structure stays visible and auditable, which reduces dropped th
 Goal: keep indexes accurate without manually re-tagging everything.
 
 1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
-2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags); use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering. Numeric chapter filters are compatibility aliases for read scopes, not mutation targets.
+2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, and keep one-sided scene links for a deliberately named relationship workflow. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
 3. Use `search_metadata` and `find_scenes` to verify scenes are discoverable under the expected filters.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.
@@ -179,7 +179,7 @@ Goal: rebuild scene-to-character links in a controlled way after imported prose
 4. Re-run `enrich_scene_characters_batch` with `dry_run=false` once the preview looks correct.
 5. If you want a destructive overwrite instead of additive merge behavior, use `replace_mode=replace` with `confirm_replace=true` deliberately.
 
-Outcome: character-link maintenance becomes a preview-first batch operation instead of a one-off regex script or manual sidecar cleanup.
+Outcome: character-link maintenance becomes a preview-first relationship repair operation instead of a one-off regex script or manual sidecar cleanup.
 
 ### 6) Post-upgrade recovery after legacy migration warnings
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.23.0",
+  "version": "3.23.2",
   "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 {
@@ -121,7 +121,7 @@ function buildRelationshipMetadataBoundaryDetails({ projectId, sceneId, blockedF
     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.",
+    next_step: "Use find_scenes, list_characters, and list_places to identify stable IDs. Use connect_character_place_evidence when the scene proves paired sheet-backed character/place evidence; use audit_relationship_metadata to review legacy sidecar/frontmatter relationship fields. Independent character-only or place-only scene links remain valid, but are not changed through update_scene_metadata.",
   };
 }
 
@@ -454,6 +454,36 @@ 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);
@@ -1061,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 when evidence is paired, and leave independent character-only/place-only repairs to a deliberately named future workflow.",
+            });
+          }
+        }
         if (sourceMeta.threads) {
           diagnostics.push({
             type: "sidecar_threads_compatibility_input",
@@ -1146,10 +1209,11 @@ 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: [
-        "Use connect_character_place_evidence for scene-backed character/place relationships.",
+        "Use connect_character_place_evidence when scene-backed character/place evidence is paired; independent one-sided links remain valid but need a deliberately named workflow.",
         "Use record_character_relationship_beat for relationship arcs between characters.",
         "Use link_reference_evidence for explicit reference evidence.",
         "Use export_project_backup when a fresh recovery snapshot is needed.",
@@ -1376,7 +1440,7 @@ export function registerMetadataTools(s, {
   // ---- connect_character_place_evidence ------------------------------------
   s.tool(
     "connect_character_place_evidence",
-    "Connect a character and place as scene-backed story evidence. This is the outcome-level workflow for character/place association: SQLite scene relationship indexes commit first, project backups refresh after commit, and scene sidecar characters/places are refreshed only as generated compatibility output.",
+    "Connect a character and place as paired scene-backed story evidence. This outcome-level workflow covers sheet-backed character/place associations: SQLite scene relationship indexes commit first, project backups refresh after commit, and scene sidecar characters/places are refreshed only as generated compatibility output. Independent character-only or place-only scene links remain valid, but are not handled by update_scene_metadata and need a deliberately named workflow if promoted later.",
     {
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
       scene_id: z.string().describe("Scene that provides the evidence for this character/place association."),
@@ -1406,7 +1470,7 @@ export function registerMetadataTools(s, {
   // ---- audit_relationship_metadata -----------------------------------------
   s.tool(
     "audit_relationship_metadata",
-    "Review relationship metadata authority, stale indexes, and retained compatibility notes without mutating SQLite or files. Use this before repair work when character/place associations, sidecar tags, scene threads, or recovery readiness look stale or ambiguous.",
+    "Review relationship metadata authority, stale indexes, retained compatibility notes, and scene character/place sidecar drift without mutating SQLite or files. Use this before repair work when character/place associations, sidecar tags, scene threads, or recovery readiness look stale or ambiguous.",
     {
       project_id: z.string().optional().describe("Optional project scope for the audit."),
     },
@@ -2280,7 +2344,7 @@ export function registerMetadataTools(s, {
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",
-    "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.",
+    "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 when evidence is paired, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Independent character-only or place-only scene links remain valid, but are intentionally not changed through this generic metadata tool. 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')."),
@@ -2297,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().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."),
+        characters:        z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, and audit_relationship_metadata for compatibility review; independent character-only evidence remains valid but needs a deliberately named workflow."),
+        places:            z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, and audit_relationship_metadata for compatibility review; independent place-only evidence remains valid but needs a deliberately named workflow."),
       }).describe("Fields to update. Only supplied keys are changed."),
     },
     async ({ scene_id, project_id, fields }) => {
@@ -2543,7 +2607,7 @@ export function registerMetadataTools(s, {
   // ---- update_place_sheet --------------------------------------------------
   s.tool(
     "update_place_sheet",
-    "Update canonical place profile fields and retained compatibility notes. The place name commits to SQLite first and refreshes project backups; associated_characters and tags are compatibility/review metadata only. For current character/place relationship authority, use connect_character_place_evidence.",
+    "Update canonical place profile fields and retained compatibility notes. The place name commits to SQLite first and refreshes project backups; associated_characters and tags are compatibility/review metadata only. Use connect_character_place_evidence when scene-backed character/place evidence is paired; independent place-only links remain valid but need a deliberately named workflow.",
     {
       place_id: z.string().describe("The place_id to update (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
       fields: z.object({
@@ -2652,7 +2716,7 @@ export function registerMetadataTools(s, {
         }),
         non_canonical_fields: ["associated_characters", "tags"].filter(field => Object.hasOwn(fields, field)),
         next_step: Object.hasOwn(fields, "associated_characters")
-          ? "Use connect_character_place_evidence to make scene-backed character/place associations authoritative."
+          ? "Use connect_character_place_evidence when paired scene-backed character/place evidence should become authoritative; independent one-sided links remain valid but need a deliberately named workflow."
           : undefined,
         ...backupMutationFields(backupResult),
       });

package/src/tools/search.js

@@ -609,7 +609,7 @@ export function registerSearchTools(s, {
   // ---- get_place_sheet -----------------------------------------------------
   s.tool(
     "get_place_sheet",
-    "Get full place details, including canonical sheet content plus retained sidecar associated_characters and tags as compatibility/review notes. Use connect_character_place_evidence for current scene-backed character/place authority. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
+    "Get full place details, including canonical sheet content plus retained sidecar associated_characters and tags as compatibility/review notes. Use connect_character_place_evidence when scene-backed character/place evidence is paired; independent place-only links remain valid and need an explicit relationship workflow rather than a place-sheet read. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
     {
       place_id: z.string().describe("The place_id to look up (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
     },

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);

package/src/workflows/workflow-catalogue.js

@@ -68,12 +68,12 @@ export const WORKFLOW_CATALOGUE = [
     label: "Track and repair story relationships",
     use_when: "Use when the user wants to track an arc, link evidence, review stale relationships, repair metadata parity, or prepare generated recovery material for relationship metadata.",
     steps: [
-      { tool: "find_scenes", note: "Identify scene_id and project_id from story context before recording relationships." },
+      { tool: "find_scenes", note: "Identify scene_id and project_id from story context before recording relationships; use list_characters and list_places when stable entity IDs need disambiguation." },
       { tool: "track_thread_arc", note: "Use when a scene should carry a storyline, subplot, setup, escalation, reveal, reversal, payoff, or other thread beat." },
-      { tool: "connect_character_place_evidence", note: "Use when a scene proves a character/place association; SQLite scene relationship indexes commit first and sidecar characters/places remain generated compatibility output." },
+      { tool: "connect_character_place_evidence", note: "Use when a scene proves paired sheet-backed character/place evidence; SQLite scene relationship indexes commit first and sidecar characters/places remain generated compatibility output. Independent character-only or place-only scene links remain valid, but need a deliberately named future workflow for daily repair." },
       { tool: "record_character_relationship_beat", note: "Use when a scene proves a relationship beat between two characters without exposing the character_relationships table." },
       { tool: "link_reference_evidence", note: "Use when scene, character, place, or reference evidence should point to a reference document; SQLite commits first and compatibility output is generated transparency." },
-      { tool: "audit_relationship_metadata", note: "Use before repair work to review stale relationship indexes and sidecar-only compatibility notes without mutating canonical state." },
+      { tool: "audit_relationship_metadata", note: "Use before repair work to review stale relationship indexes, retained sidecar/frontmatter characters or places, and compatibility drift without mutating canonical state." },
       { tool: "suggest_scene_references", note: "Use preview first to review candidate scene-reference links from character/place evidence; use apply only after the relationship outcome is intended." },
       { tool: "enrich_scene_characters_batch", note: "Use dry_run first when prose-derived character relationship parity needs repair across multiple scenes; apply mode syncs SQLite after compatibility output and refreshes backups for changed scenes." },
       { tool: "diagnose_project_backups", note: "Relationship mutation tools refresh project backups after canonical commits; run this if backup_warnings were returned or recovery readiness matters." },
@@ -101,9 +101,9 @@ export const WORKFLOW_CATALOGUE = [
     steps: [
       { tool: "sync", note: "Refresh SQLite indexes from current compatibility inputs, then review warnings instead of patching sidecars as the first repair step." },
       { tool: "diagnose_structure", note: "Use when sidecar, frontmatter, folder, chapter, epigraph, or generated-export structure appears to disagree with SQLite canonical state." },
-      { tool: "audit_relationship_metadata", note: "Use when sidecar threads, tags, flags, associated_characters, characters, places, or reference aliases need authority classification before repair." },
+      { tool: "audit_relationship_metadata", note: "Use when sidecar threads, tags, flags, associated_characters, characters, places, or reference aliases need authority classification before repair; relationship fields are compatibility input/review evidence, not generic metadata writes." },
       { tool: "track_thread_arc", note: "Use for current thread authority instead of editing sidecar threads." },
-      { tool: "connect_character_place_evidence", note: "Use for current scene-backed character/place authority instead of editing sidecar relationship lists." },
+      { tool: "connect_character_place_evidence", note: "Use for paired scene-backed character/place evidence instead of editing sidecar relationship lists or sending characters/places through update_scene_metadata; independent one-sided links remain valid but are outside this generic metadata path." },
       { tool: "link_reference_evidence", note: "Use for current reference-link authority instead of editing sidecar/frontmatter aliases." },
       { tool: "export_project_backup", note: "Generate a recovery snapshot from SQLite canonical state after meaningful canonical migration or repair work; editing backup artifacts does not mutate current state." },
     ],