@hanna84/mcp-writing 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -4,11 +4,31 @@ 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.0.0](https://github.com/hannasdev/mcp-writing.git
+#### [v3.1.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v3.1.0...v3.1.1)
+
+- fix: surface runtime warning for invalid PROSE_STYLEGUIDE_ENFORCEMENT_MODE [`#167`](https://github.com/hannasdev/mcp-writing.git
+/pull/167)
+
+#### [v3.1.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v3.0.0...v3.1.0)
+
+> 2 May 2026
+
+- feat(editing): enforce styleguide automatically in edit flow [`#166`](https://github.com/hannasdev/mcp-writing.git
+/pull/166)
+- Release 3.1.0 [`ad1106c`](https://github.com/hannasdev/mcp-writing.git
+/commit/ad1106ca4099777d9b05556dfd9cf75de4f030f1)
+
+### [v3.0.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.18.1...v3.0.0)
 
+> 2 May 2026
+
 - feat!: improve MCP tooling usability and harden scene-id safety [`#165`](https://github.com/hannasdev/mcp-writing.git
 /pull/165)
+- Release 3.0.0 [`d7541b1`](https://github.com/hannasdev/mcp-writing.git
+/commit/d7541b1511dbe92c514cb0435f94b8626be5ea29)
 
 #### [v2.18.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.18.0...v2.18.1)

package/package.json

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

@@ -71,7 +71,14 @@ const OWNERSHIP_GUARD_MODE_RAW = (process.env.OWNERSHIP_GUARD_MODE ?? "warn").tr
 const OWNERSHIP_GUARD_MODE = OWNERSHIP_GUARD_MODE_RAW === "fail" || OWNERSHIP_GUARD_MODE_RAW === "warn"
   ? OWNERSHIP_GUARD_MODE_RAW
   : "warn";
+const STYLEGUIDE_ENFORCEMENT_MODE_RAW = (process.env.PROSE_STYLEGUIDE_ENFORCEMENT_MODE ?? "warn").trim().toLowerCase();
+const STYLEGUIDE_ENFORCEMENT_MODE = STYLEGUIDE_ENFORCEMENT_MODE_RAW === "off"
+  || STYLEGUIDE_ENFORCEMENT_MODE_RAW === "warn"
+  || STYLEGUIDE_ENFORCEMENT_MODE_RAW === "required"
+  ? STYLEGUIDE_ENFORCEMENT_MODE_RAW
+  : "warn";
 const OWNERSHIP_GUARD_MODE_RAW_DISPLAY = JSON.stringify(OWNERSHIP_GUARD_MODE_RAW);
+const STYLEGUIDE_ENFORCEMENT_MODE_RAW_DISPLAY = JSON.stringify(STYLEGUIDE_ENFORCEMENT_MODE_RAW);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const ROOT_DIR = path.resolve(__dirname, "..");
@@ -213,6 +220,9 @@ const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics({
   ownershipGuardModeRaw: OWNERSHIP_GUARD_MODE_RAW,
   ownershipGuardMode: OWNERSHIP_GUARD_MODE,
   ownershipGuardModeRawDisplay: OWNERSHIP_GUARD_MODE_RAW_DISPLAY,
+  styleguideEnforcementModeRaw: STYLEGUIDE_ENFORCEMENT_MODE_RAW,
+  styleguideEnforcementMode: STYLEGUIDE_ENFORCEMENT_MODE,
+  styleguideEnforcementModeRawDisplay: STYLEGUIDE_ENFORCEMENT_MODE_RAW_DISPLAY,
   syncDirWritable: SYNC_DIR_WRITABLE,
   syncDirAbs: SYNC_DIR_ABS,
   syncOwnershipDiagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
@@ -410,6 +420,7 @@ function createMcpServer() {
     isPathCandidateInsideSyncDir,
     pendingProposals,
     generateProposalId,
+    STYLEGUIDE_ENFORCEMENT_MODE,
   };
   registerSyncTools(s, toolContext);
   registerSearchTools(s, toolContext);
@@ -434,6 +445,7 @@ function createMcpServer() {
         permission_diagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
         git_available: GIT_AVAILABLE,
         git_enabled: GIT_ENABLED,
+        styleguide_enforcement_mode: STYLEGUIDE_ENFORCEMENT_MODE,
         http_port: HTTP_PORT,
         runtime_warnings: RUNTIME_DIAGNOSTICS.warnings,
         setup_recommendations: RUNTIME_DIAGNOSTICS.recommendations,

package/src/runtime/runtime-diagnostics.js

@@ -6,9 +6,12 @@
  * is straightforward to test.
  *
  * @param {object} opts
- * @param {string}  opts.ownershipGuardModeRaw      Raw env value before normalisation
+ * @param {string}  opts.ownershipGuardModeRaw      Trimmed/lowercased env token before enum validation
  * @param {string}  opts.ownershipGuardMode          Normalised value ("warn" | "fail")
  * @param {string}  opts.ownershipGuardModeRawDisplay JSON.stringify of the raw value
+ * @param {string}  opts.styleguideEnforcementModeRaw Trimmed/lowercased env token before enum validation
+ * @param {string}  opts.styleguideEnforcementMode    Normalised value ("off" | "warn" | "required")
+ * @param {string}  opts.styleguideEnforcementModeRawDisplay JSON.stringify of the raw value
  * @param {boolean} opts.syncDirWritable
  * @param {string}  opts.syncDirAbs                 Resolved absolute path shown in messages
  * @param {object}  opts.syncOwnershipDiagnostics   Result of getSyncOwnershipDiagnostics()
@@ -20,6 +23,9 @@ export function getRuntimeDiagnostics({
   ownershipGuardModeRaw,
   ownershipGuardMode,
   ownershipGuardModeRawDisplay,
+  styleguideEnforcementModeRaw,
+  styleguideEnforcementMode,
+  styleguideEnforcementModeRawDisplay,
   syncDirWritable,
   syncDirAbs,
   syncOwnershipDiagnostics,
@@ -36,6 +42,13 @@ export function getRuntimeDiagnostics({
     recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
   }
 
+  if (styleguideEnforcementModeRaw !== styleguideEnforcementMode) {
+    warnings.push(
+      `STYLEGUIDE_ENFORCEMENT_MODE_INVALID: Unsupported PROSE_STYLEGUIDE_ENFORCEMENT_MODE=${styleguideEnforcementModeRawDisplay}. Falling back to 'warn'.`
+    );
+    recommendations.push("Set PROSE_STYLEGUIDE_ENFORCEMENT_MODE to one of 'off', 'warn', or 'required'.");
+  }
+
   if (syncOwnershipDiagnostics.runtime_uid_override_ignored) {
     warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
     recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");

package/src/tools/editing.js

@@ -1,9 +1,17 @@
 import { z } from "zod";
 import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
 import matter from "gray-matter";
 import yaml from "js-yaml";
 import { createSnapshot, listSnapshots } from "../core/git.js";
 import { getFileWriteDiagnostics, readMeta, indexSceneFile } from "../sync/sync.js";
+import { resolveStyleguideConfig } from "../styleguide/prose-styleguide.js";
+import {
+  PROSE_STYLEGUIDE_SKILL_BASENAME,
+  PROSE_STYLEGUIDE_SKILL_DIRNAME,
+} from "../styleguide/prose-styleguide-skill.js";
+import { analyzeSceneStyleguideDrift } from "../styleguide/prose-styleguide-drift.js";
 
 function renderSceneContent(metadata, revisedProse) {
   const hasFrontmatter = metadata && Object.keys(metadata).length > 0;
@@ -13,10 +21,197 @@ function renderSceneContent(metadata, revisedProse) {
     : `${normalizedProse}\n`;
 }
 
+function digestFor(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function buildStyleguideFingerprint({
+  resolvedConfig,
+  sources,
+  skillDigest,
+  setupRequired,
+}) {
+  return digestFor(JSON.stringify({
+    resolved_config: resolvedConfig ?? null,
+    sources: sources ?? [],
+    skill_digest: skillDigest ?? null,
+    setup_required: Boolean(setupRequired),
+  }));
+}
+
+function resolveStyleguideSnapshot({ syncDir, projectId, errorResponse }) {
+  const resolved = resolveStyleguideConfig({
+    syncDir,
+    projectId,
+  });
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      response: errorResponse(
+        resolved.error.code,
+        resolved.error.message,
+        resolved.error.details
+      ),
+    };
+  }
+
+  const skillPath = path.join(
+    syncDir,
+    PROSE_STYLEGUIDE_SKILL_DIRNAME,
+    PROSE_STYLEGUIDE_SKILL_BASENAME
+  );
+  let skillExists;
+  let skillDigest = null;
+  try {
+    skillExists = fs.existsSync(skillPath);
+    if (skillExists) {
+      skillDigest = digestFor(fs.readFileSync(skillPath, "utf8"));
+    }
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    return {
+      ok: false,
+      response: errorResponse(
+        "STYLEGUIDE_SKILL_IO_ERROR",
+        "Failed to read skills/prose-styleguide.md while resolving styleguide snapshot.",
+        {
+          file_path: skillPath,
+          reason: err.message,
+        }
+      ),
+    };
+  }
+  const fingerprint = buildStyleguideFingerprint({
+    resolvedConfig: resolved.resolved_config,
+    sources: resolved.sources,
+    skillDigest,
+    setupRequired: resolved.setup_required,
+  });
+
+  return {
+    ok: true,
+    snapshot: {
+      project_id: projectId ?? null,
+      config_found: resolved.config_found,
+      setup_required: resolved.setup_required,
+      sources: resolved.sources,
+      resolved_config: resolved.resolved_config,
+      skill_file_path: skillPath,
+      skill_found: Boolean(skillExists),
+      skill_digest: skillDigest,
+      fingerprint,
+    },
+  };
+}
+
+function evaluateStyleguidePolicy({
+  snapshot,
+  revisedProse,
+  bypassStyleguide,
+  bypassReason,
+  enforcementMode,
+  errorResponse,
+}) {
+  if (bypassStyleguide && !bypassReason) {
+    return {
+      ok: false,
+      response: errorResponse(
+        "STYLEGUIDE_BYPASS_REASON_REQUIRED",
+        "bypass_reason is required when bypass_styleguide=true."
+      ),
+    };
+  }
+
+  const warnings = [];
+  if (enforcementMode !== "off") {
+    if (snapshot.setup_required || !snapshot.config_found) {
+      if (enforcementMode === "required" && !bypassStyleguide) {
+        return {
+          ok: false,
+          response: errorResponse(
+            "STYLEGUIDE_CONFIG_REQUIRED",
+            "Cannot propose prose edits before prose-styleguide.config.yaml is configured.",
+            {
+              project_id: snapshot.project_id,
+              next_step: "Run setup_prose_styleguide_config (or bootstrap_prose_styleguide_config), then retry propose_edit.",
+            }
+          ),
+        };
+      }
+      warnings.push("No prose-styleguide.config.yaml is currently resolved for this scene.");
+    }
+
+    if (!snapshot.skill_found) {
+      if (enforcementMode === "required" && !bypassStyleguide) {
+        return {
+          ok: false,
+          response: errorResponse(
+            "STYLEGUIDE_SKILL_REQUIRED",
+            "Cannot propose prose edits before skills/prose-styleguide.md exists.",
+            {
+              next_step: "Run setup_prose_styleguide_skill, then retry propose_edit.",
+            }
+          ),
+        };
+      }
+      warnings.push("skills/prose-styleguide.md was not found at sync root.");
+    }
+  }
+
+  const canApply =
+    enforcementMode !== "off"
+    && !bypassStyleguide
+    && snapshot.config_found
+    && !snapshot.setup_required
+    && Boolean(snapshot.resolved_config);
+
+  const analysis = canApply
+    ? analyzeSceneStyleguideDrift({
+      prose: revisedProse,
+      resolvedConfig: snapshot.resolved_config,
+    })
+    : { observed: {}, drift: [] };
+
+  const violations = analysis.drift.map((entry) => ({
+    field: entry.field,
+    declared: entry.declared,
+    observed: entry.observed,
+    severity: "error",
+  }));
+
+  if (enforcementMode === "required" && violations.length > 0 && !bypassStyleguide) {
+    return {
+      ok: false,
+      response: errorResponse(
+        "STYLEGUIDE_VIOLATIONS",
+        "Revised prose violates required styleguide conventions.",
+        {
+          violations,
+          next_step: "Revise prose to match conventions or retry with bypass_styleguide=true and a bypass_reason.",
+        }
+      ),
+    };
+  }
+
+  return {
+    ok: true,
+    policy: {
+      enforcement_mode: enforcementMode,
+      bypass_used: Boolean(bypassStyleguide),
+      bypass_reason: bypassStyleguide ? bypassReason : null,
+      styleguide_applied: canApply,
+      warnings,
+      observed_signals: analysis.observed,
+      violations,
+    },
+  };
+}
+
 export function registerEditingTools(s, {
   db,
   SYNC_DIR,
   GIT_ENABLED,
+  STYLEGUIDE_ENFORCEMENT_MODE,
   errorResponse,
   jsonResponse,
   pendingProposals,
@@ -31,8 +226,10 @@ export function registerEditingTools(s, {
       project_id: z.string().optional().describe("Optional project ID to disambiguate duplicate scene IDs across projects."),
       instruction: z.string().describe("A brief instruction for the edit (e.g. 'Tighten the opening paragraph'). Used in the git commit message."),
       revised_prose: z.string().describe("The complete revised prose text for the scene."),
+      bypass_styleguide: z.boolean().optional().describe("If true, bypasses automatic styleguide checks for this proposal."),
+      bypass_reason: z.string().optional().describe("Required when bypass_styleguide=true. Explains why this edit should ignore styleguide checks."),
     },
-    async ({ scene_id, project_id, instruction, revised_prose }) => {
+    async ({ scene_id, project_id, instruction, revised_prose, bypass_styleguide = false, bypass_reason }) => {
       if (!GIT_ENABLED) {
         return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported. Ensure git is installed and the sync directory is writable.");
       }
@@ -58,6 +255,27 @@ export function registerEditingTools(s, {
         scene = scenes[0];
       }
 
+      const styleguideSnapshotResult = resolveStyleguideSnapshot({
+        syncDir: SYNC_DIR,
+        projectId: scene.project_id,
+        errorResponse,
+      });
+      if (!styleguideSnapshotResult.ok) {
+        return styleguideSnapshotResult.response;
+      }
+
+      const styleguidePolicy = evaluateStyleguidePolicy({
+        snapshot: styleguideSnapshotResult.snapshot,
+        revisedProse: revised_prose,
+        bypassStyleguide: bypass_styleguide,
+        bypassReason: bypass_reason,
+        enforcementMode: STYLEGUIDE_ENFORCEMENT_MODE,
+        errorResponse,
+      });
+      if (!styleguidePolicy.ok) {
+        return styleguidePolicy.response;
+      }
+
       try {
         const raw = fs.readFileSync(scene.file_path, "utf8");
         const { data: metadata, content: currentProse } = matter(raw);
@@ -90,6 +308,8 @@ export function registerEditingTools(s, {
           rendered_content: renderedContent,
           original_prose: currentProse,
           metadata,
+          styleguide_snapshot: styleguideSnapshotResult.snapshot,
+          styleguide_policy: styleguidePolicy.policy,
           created_at: new Date().toISOString(),
         });
 
@@ -107,6 +327,13 @@ export function registerEditingTools(s, {
           instruction,
           diff_preview: diffPreview,
           noop,
+          styleguide: {
+            ...styleguidePolicy.policy,
+            fingerprint: styleguideSnapshotResult.snapshot.fingerprint,
+            config_found: styleguideSnapshotResult.snapshot.config_found,
+            skill_found: styleguideSnapshotResult.snapshot.skill_found,
+            sources: styleguideSnapshotResult.snapshot.sources,
+          },
           note: noop
             ? "This proposal matches the current scene file. Calling commit_edit will be a no-op."
             : "Review the diff above. Call commit_edit with this proposal_id to apply the change.",
@@ -167,6 +394,35 @@ export function registerEditingTools(s, {
         return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for project '${proposal.project_id}', not '${project_id}'.`);
       }
 
+      if (
+        proposal.styleguide_snapshot
+        && proposal.styleguide_policy
+        && proposal.styleguide_policy.bypass_used !== true
+      ) {
+        const latestStyleguideSnapshot = resolveStyleguideSnapshot({
+          syncDir: SYNC_DIR,
+          projectId: proposal.project_id,
+          errorResponse,
+        });
+        if (!latestStyleguideSnapshot.ok) {
+          return latestStyleguideSnapshot.response;
+        }
+
+        if (latestStyleguideSnapshot.snapshot.fingerprint !== proposal.styleguide_snapshot.fingerprint) {
+          return errorResponse(
+            "STYLEGUIDE_CHANGED_SINCE_PROPOSAL",
+            "Styleguide inputs changed after this proposal was created. Re-run propose_edit against the latest styleguide before commit.",
+            {
+              proposal_id,
+              project_id: proposal.project_id ?? null,
+              previous_fingerprint: proposal.styleguide_snapshot.fingerprint,
+              current_fingerprint: latestStyleguideSnapshot.snapshot.fingerprint,
+              next_step: "Call propose_edit again to regenerate this revision with current styleguide rules.",
+            }
+          );
+        }
+      }
+
       try {
         const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
         if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {