@hanna84/mcp-writing 3.21.2 → 3.22.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.22.0](https://github.com/hannasdev/mcp-writing/compare/v3.21.3...v3.22.0)
+
+- feat(metadata): add outcome relationship workflows [`#225`](https://github.com/hannasdev/mcp-writing/pull/225)
+
+#### [v3.21.3](https://github.com/hannasdev/mcp-writing/compare/v3.21.2...v3.21.3)
+
+> 28 May 2026
+
+- fix(metadata): preserve sidecar structure fields on generic writes [`#224`](https://github.com/hannasdev/mcp-writing/pull/224)
+- Release 3.21.3 [`91bc41f`](https://github.com/hannasdev/mcp-writing/commit/91bc41f98e6acf0f46cf93f329e1ecebad2e2305)
+
 #### [v3.21.2](https://github.com/hannasdev/mcp-writing/compare/v3.21.1...v3.21.2)
 
+> 28 May 2026
+
 - docs: accept architecture snapshot milestone [`#223`](https://github.com/hannasdev/mcp-writing/pull/223)
+- Release 3.21.2 [`7f0e627`](https://github.com/hannasdev/mcp-writing/commit/7f0e62741059ad487577e7295ea75564fd64d33a)
 
 #### [v3.21.1](https://github.com/hannasdev/mcp-writing/compare/v3.21.0...v3.21.1)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.21.2",
+  "version": "3.22.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/scripts/normalize-scene-characters.mjs

@@ -2,7 +2,7 @@
 import path from "node:path";
 import { openDb } from "../core/db.js";
 import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../sync/scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../sync/sync.js";
+import { readMeta, readSourceMeta, syncAll, writeMeta } from "../sync/sync.js";
 
 function readRequiredValue(argv, index, option) {
   const value = argv[index + 1];
@@ -138,11 +138,11 @@ function runNormalization({ syncDir, projectId, write, limit }) {
       if (!normalized.changed) continue;
 
       if (write) {
-        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
-          ...meta,
+        const { sourceMeta } = readSourceMeta(scene.file_path, syncDir, { writable: true });
+        writeMeta(scene.file_path, {
+          ...sourceMeta,
           characters: normalized.after,
-        }).meta;
-        writeMeta(scene.file_path, updatedMeta, { syncDir });
+        }, { syncDir });
       }
 
       changed.push({

package/src/sync/scene-character-batch.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import matter from "gray-matter";
 import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
-import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
+import { readSourceMeta, writeMeta } from "./sync.js";
 
 function normalizeCharacterRows(rows) {
   return buildCharacterNormalizationContext(rows);
@@ -138,7 +138,7 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
     try {
       const raw = fs.readFileSync(scene.file_path, "utf8");
       const { content: prose } = matter(raw);
-      const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
+      const { sourceMeta: meta } = readSourceMeta(scene.file_path, syncDir, { writable: !dry_run });
 
       const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
       const normalized_before_characters = [...new Set(
@@ -169,10 +169,10 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
       const changed = added.length > 0 || removed.length > 0;
 
       if (!dry_run && changed) {
-        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+        const updatedMeta = {
           ...meta,
           characters: after_characters,
-        }).meta;
+        };
 
         writeMeta(scene.file_path, updatedMeta, { syncDir });
       }
@@ -234,6 +234,15 @@ export async function runSceneCharacterBatch({ syncDir, args, onProgress, should
     cancelled: Boolean(typeof shouldCancel === "function" && shouldCancel() && processed_scenes < targetScenes.length),
     project_id,
     dry_run: Boolean(dry_run),
+    relationship_authority: {
+      canonical_owner: "SQLite scene_characters",
+      compatibility_source: "scene sidecar characters",
+      compatibility_mutation_surface: false,
+      apply_order: dry_run ? "preview_only" : "compatibility_output_then_sync_index",
+      note: dry_run
+        ? "Dry run only reviews prose-derived character repairs."
+        : "M4 retains this batch repair as a prose-derived compatibility path; completion syncs the SQLite relationship index and refreshes backups for changed scenes.",
+    },
     total_scenes: targetScenes.length,
     processed_scenes,
     scenes_changed,

package/src/sync/sync.js

@@ -494,11 +494,12 @@ export function parseFile(filePath) {
 }
 
 /**
- * Read metadata for a scene file. Priority: sidecar > frontmatter.
- * If sidecar doesn't exist but frontmatter does, auto-generates the sidecar.
- * Returns { meta, sidecarGenerated }.
+ * Read source metadata for a scene file. Priority: sidecar > frontmatter.
+ * Does not apply path-derived structural normalization or auto-generate sidecars.
+ * Generic metadata writers use this so non-structural updates do not mirror
+ * path-derived structure fields into sidecars.
  */
-export function readMeta(filePath, syncDir, { writable = false } = {}) {
+export function readSourceMeta(filePath, syncDir, { writable = false } = {}) {
   const sidecar = sidecarPath(filePath);
   const syncDirAbs = path.resolve(syncDir);
 
@@ -517,26 +518,45 @@ export function readMeta(filePath, syncDir, { writable = false } = {}) {
     }
     const raw = fs.readFileSync(sidecar, "utf8");
     const parsed = parseYaml(raw) ?? {};
-    return { ...normalizeSceneMetaForPath(syncDir, filePath, parsed), sourceMeta: parsed, sidecarGenerated: false };
+    return { meta: parsed, sourceMeta: parsed, source: "sidecar", sidecarGenerated: false };
   }
 
   // Fall back to frontmatter
   const { data: frontmatter } = parseFile(filePath);
   if (!Object.keys(frontmatter).length) {
-    return { ...normalizeSceneMetaForPath(syncDir, filePath, {}), sourceMeta: {}, sidecarGenerated: false };
+    return { meta: {}, sourceMeta: {}, source: "empty", sidecarGenerated: false };
+  }
+
+  return { meta: frontmatter, sourceMeta: frontmatter, source: "frontmatter", sidecarGenerated: false };
+}
+
+/**
+ * Read metadata for a scene file. Priority: sidecar > frontmatter.
+ * If sidecar doesn't exist but frontmatter does, auto-generates the sidecar.
+ * Returns { meta, sidecarGenerated }.
+ */
+export function readMeta(filePath, syncDir, { writable = false } = {}) {
+  const sourceRead = readSourceMeta(filePath, syncDir, { writable });
+
+  if (sourceRead.source === "sidecar" || sourceRead.source === "empty") {
+    return {
+      ...normalizeSceneMetaForPath(syncDir, filePath, sourceRead.sourceMeta),
+      sourceMeta: sourceRead.sourceMeta,
+      sidecarGenerated: false,
+    };
   }
 
-  const normalized = normalizeSceneMetaForPath(syncDir, filePath, frontmatter);
+  const normalized = normalizeSceneMetaForPath(syncDir, filePath, sourceRead.sourceMeta);
 
   // Auto-migrate: write sidecar from frontmatter (only if writable)
   if (writable) {
     try {
       writeMeta(filePath, normalized.meta, { syncDir });
-      return { ...normalized, sourceMeta: frontmatter, sidecarGenerated: true };
+      return { ...normalized, sourceMeta: sourceRead.sourceMeta, sidecarGenerated: true };
     } catch { /* empty */ }
   }
 
-  return { ...normalized, sourceMeta: frontmatter, sidecarGenerated: false };
+  return { ...normalized, sourceMeta: sourceRead.sourceMeta, sidecarGenerated: false };
 }
 
 /**