@hanna84/mcp-writing 3.22.0 → 3.22.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.22.2](https://github.com/hannasdev/mcp-writing/compare/v3.22.1...v3.22.2)
+
+- docs: close architecture alignment follow-up initiative [`#227`](https://github.com/hannasdev/mcp-writing/pull/227)
+
+#### [v3.22.1](https://github.com/hannasdev/mcp-writing/compare/v3.22.0...v3.22.1)
+
+> 28 May 2026
+
+- docs: document sidecar compatibility migration [`#226`](https://github.com/hannasdev/mcp-writing/pull/226)
+- Release 3.22.1 [`43c98bc`](https://github.com/hannasdev/mcp-writing/commit/43c98bc56ea4f532926569eda3f77213d6b4a2c8)
+
 #### [v3.22.0](https://github.com/hannasdev/mcp-writing/compare/v3.21.3...v3.22.0)
 
+> 28 May 2026
+
 - feat(metadata): add outcome relationship workflows [`#225`](https://github.com/hannasdev/mcp-writing/pull/225)
+- Release 3.22.0 [`972d6af`](https://github.com/hannasdev/mcp-writing/commit/972d6aff4e6b237cfa23f74830181be3486f75fa)
 
 #### [v3.21.3](https://github.com/hannasdev/mcp-writing/compare/v3.21.2...v3.21.3)
 

package/README.md

@@ -27,10 +27,10 @@ For VS Code-native setup flows (including prose styleguide setup), use:
 Instead of feeding an entire manuscript to an AI and hoping it fits in the context window, `mcp-writing` builds a structured index from your scene files. The AI queries that index first — finding relevant characters, beats, and loglines — then loads only the specific prose it needs.
 
 **Current status:**
-- **Core platform complete:** Metadata-first analysis, sidecar-backed metadata maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
+- **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:** Post-initiative stabilization and backlog selection.
+- **Active development:** Architecture Alignment Follow-up M5, documenting sidecar compatibility, migration, and deprecation expectations.
 - **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.
 
@@ -48,6 +48,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 | [mcp-writing-vscode](https://github.com/hannasdev/mcp-writing-vscode) | VS Code extension for client-native setup flows |
 | [docs/guides/docker.md](docs/guides/docker.md) | Docker Compose, deployment operations, MCP gateway notes |
 | [docs/guides/backup-recovery.md](docs/guides/backup-recovery.md) | Project backup artifacts, diagnostics, and explicit restore workflow |
+| [docs/guides/sidecar-compatibility.md](docs/guides/sidecar-compatibility.md) | Sidecar compatibility roles, migration posture, and daily-work authority boundaries |
 | [docs/foundations/managed-structure-contract.md](docs/foundations/managed-structure-contract.md) | Design boundaries for structural mutation, generated views, import, and maintenance workflows |
 | [docs/agents/tools.md](docs/agents/tools.md) | Full tool reference — auto-generated from source |
 | [docs/agents/README.md](docs/agents/README.md) | Index of agent-focused guidance, examples, and boot files |
@@ -142,7 +143,7 @@ Goal: make sure subplot threads progress intentionally and resolve on time.
 
 1. Run `list_threads` for the project.
 2. Use `get_thread_arc` to inspect scene order and beat labels for each thread.
-3. When a beat is missing, call `upsert_thread_link` to add or update it on the right scene.
+3. When a beat is missing, call `track_thread_arc` to add or update it on the right scene.
 4. Re-run `get_thread_arc` to confirm pacing and coverage.
 
 Outcome: subplot structure stays visible and auditable, which reduces dropped threads in late drafts.
@@ -185,7 +186,7 @@ Outcome: character-link maintenance becomes a preview-first batch operation inst
 Goal: recover index confidence quickly when legacy upgrade warnings indicate ambiguous rows were skipped.
 
 1. Start by checking `get_runtime_config` (or `describe_workflows`) and confirm whether `db_migration_warnings` contains `LEGACY_JOIN_ROWS_SKIPPED`.
-2. If present, run `sync` immediately to rebuild scene relationships from current sidecars and prose metadata.
+2. If present, run `sync` immediately to rebuild scene relationships from compatibility sidecars and prose metadata.
 3. Continue normal discovery (`find_scenes`, `get_arc`, `get_thread_arc`) and watch for stale-metadata warnings.
 4. When you touch stale scenes, run `enrich_scene(scene_id, project_id)` to recover metadata parity incrementally.
 5. If many scenes remain stale, switch to `enrich_scene_characters_batch` (dry-run first) for broader catch-up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.22.0",
+  "version": "3.22.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/index.js

@@ -336,7 +336,7 @@ function createMcpServer() {
   // ---- describe_workflows --------------------------------------------------
   s.tool(
     "describe_workflows",
-    "Return the default workflow map and current project context for this server. Call this first in most sessions and again whenever you are unsure what to do next. Never write scripts to invoke tools — call them directly.",
+    "Return the default workflow map and current project context for this server. Call this first in most sessions and again whenever you are unsure what to do next. Treat sidecars, frontmatter, Scrivener-derived fields, generated exports, and backups by their named compatibility, review, or recovery roles; use outcome workflows for current SQLite-canonical structure and relationship changes. Never write scripts to invoke tools — call them directly.",
     {},
     async () => {
       const projectRow = db.prepare(
@@ -453,6 +453,7 @@ function createMcpServer() {
           "When calling bootstrap_prose_styleguide_config or check_prose_styleguide_drift, set max_scenes to context.scene_count to avoid the default limit.",
           "Use context.setup_contract.styleguide_setup_status to decide whether styleguide setup is missing/invalid and advisory/blocking.",
           "Styleguide tools resolve config in priority order: project_root > universe_root > sync_root. If any styleguide_exists field is true, a config exists and styleguide tools will work. For invalid setup states, use setup_contract plan preview actions (which may set overwrite=true for repair).",
+          "Treat sidecars, frontmatter, Scrivener-derived fields, generated exports, and project backups by their named compatibility, review, or recovery roles. Use outcome workflows for current SQLite-canonical structure and relationship changes.",
           ...(DB_STARTUP_WARNINGS.length > 0
             ? ["Database migration warnings are present in context.db_migration_warnings. Run sync() now, then run enrich_scene(scene_id, project_id) for stale scenes you touch."]
             : []),

package/src/workflows/workflow-catalogue.js

@@ -94,6 +94,20 @@ export const WORKFLOW_CATALOGUE = [
       { tool: "link_reference_evidence", note: "Use when the repair is a known evidence relationship rather than a suggestion-review workflow." },
     ],
   },
+  {
+    id: "sidecar_compatibility_migration",
+    label: "Migrate legacy sidecar expectations",
+    use_when: "Use when an existing project, prompt, or external workflow still treats .meta.yaml sidecars, frontmatter, or Scrivener-derived fields as the place to make structural or relationship changes.",
+    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: "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: "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." },
+    ],
+  },
   {
     id: "structure_assignment",
     label: "Manage chapter structure",