@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.17

package/lib/pen-persistence.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const crypto = require("crypto");
 const { spawnSync } = require("child_process");
 
 const DEFAULT_PEN_VERSION = "2.9";
@@ -151,6 +152,23 @@ function normalizeVariablesPayload(payload) {
   throw new Error("Variables payload must be an object or an object with a `variables` key.");
 }
 
+function canonicalizeJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeJson(item));
+  }
+
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  return Object.keys(value)
+    .sort()
+    .reduce((accumulator, key) => {
+      accumulator[key] = canonicalizeJson(value[key]);
+      return accumulator;
+    }, {});
+}
+
 function buildPenDocument({ version = DEFAULT_PEN_VERSION, nodes, variables }) {
   const document = {
     version,
@@ -165,6 +183,28 @@ function buildPenDocument({ version = DEFAULT_PEN_VERSION, nodes, variables }) {
   return document;
 }
 
+function hashPenDocument(document) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonicalizeJson(document)))
+    .digest("hex");
+}
+
+function getStandardPenStatePath(outputPath) {
+  const targetPath = path.resolve(outputPath);
+  const marker = `${path.sep}.da-vinci${path.sep}designs${path.sep}`;
+  const markerIndex = targetPath.indexOf(marker);
+
+  if (markerIndex < 0) {
+    return `${targetPath}.meta.json`;
+  }
+
+  const projectRoot = targetPath.slice(0, markerIndex);
+  const relativePenPath = targetPath.slice(markerIndex + marker.length);
+  const stateFileName = `${relativePenPath.split(path.sep).join("__")}.json`;
+  return path.join(projectRoot, ".da-vinci", "state", "pens", stateFileName);
+}
+
 function writePenDocumentAtomic(outputPath, document) {
   const targetPath = path.resolve(outputPath);
   const targetDir = path.dirname(targetPath);
@@ -179,6 +219,47 @@ function writePenDocumentAtomic(outputPath, document) {
   return targetPath;
 }
 
+function writeJsonFileAtomic(outputPath, payload) {
+  const targetPath = path.resolve(outputPath);
+  const targetDir = path.dirname(targetPath);
+  const tempPath = path.join(
+    targetDir,
+    `.${path.basename(targetPath)}.tmp-${process.pid}-${Date.now()}`
+  );
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  fs.renameSync(tempPath, targetPath);
+  return targetPath;
+}
+
+function buildPenState(outputPath, document, options = {}) {
+  return {
+    schema: 1,
+    source: options.source || "write-pen",
+    penPath: path.resolve(outputPath),
+    version: document.version || DEFAULT_PEN_VERSION,
+    snapshotHash: hashPenDocument(document),
+    topLevelIds: Array.isArray(document.children) ? document.children.map((node) => node.id) : [],
+    topLevelCount: Array.isArray(document.children) ? document.children.length : 0,
+    persistedAt: options.persistedAt || new Date().toISOString()
+  };
+}
+
+function writePenStateAtomic(outputPath, state) {
+  const statePath = getStandardPenStatePath(outputPath);
+  writeJsonFileAtomic(statePath, state);
+  return statePath;
+}
+
+function readPenState(outputPath) {
+  const statePath = getStandardPenStatePath(outputPath);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  return readJsonPayload(statePath);
+}
+
 function runPencilInteractive(inputPath, commands, options = {}) {
   const pencilBin = options.pencilBin || "pencil";
   const unusedOutput = path.join(
@@ -245,6 +326,8 @@ function writePenFromPayloadFiles(options) {
   });
 
   writePenDocumentAtomic(outputPath, document);
+  const state = buildPenState(outputPath, document, { source: "write-pen" });
+  const statePath = writePenStateAtomic(outputPath, state);
 
   const verification = options.verifyWithPencil
     ? verifyPenFileWithPencil(outputPath, {
@@ -256,7 +339,9 @@ function writePenFromPayloadFiles(options) {
   return {
     outputPath,
     document,
-    verification
+    verification,
+    state,
+    statePath
   };
 }
 
@@ -293,6 +378,8 @@ function snapshotPenFile(options) {
   });
 
   writePenDocumentAtomic(outputPath, document);
+  const state = buildPenState(outputPath, document, { source: "snapshot-pen" });
+  const statePath = writePenStateAtomic(outputPath, state);
 
   const verification = options.verifyWithPencil
     ? verifyPenFileWithPencil(outputPath, {
@@ -305,7 +392,98 @@ function snapshotPenFile(options) {
     inputPath,
     outputPath,
     document,
-    verification
+    verification,
+    state,
+    statePath
+  };
+}
+
+function readPenDocument(inputPath) {
+  return readJsonPayload(inputPath);
+}
+
+function ensurePenFile(options) {
+  const outputPath = path.resolve(options.outputPath);
+  const exists = fs.existsSync(outputPath);
+  let document;
+  let created = false;
+
+  if (exists) {
+    document = readPenDocument(outputPath);
+    if (!Array.isArray(document.children)) {
+      throw new Error(`Existing .pen file is invalid or missing \`children\`: ${outputPath}`);
+    }
+  } else {
+    document = buildPenDocument({
+      version: options.version || DEFAULT_PEN_VERSION,
+      nodes: { nodes: [] },
+      variables: {}
+    });
+    writePenDocumentAtomic(outputPath, document);
+    created = true;
+  }
+
+  const state = buildPenState(outputPath, document, {
+    source: created ? "ensure-pen:create" : "ensure-pen:existing"
+  });
+  const statePath = writePenStateAtomic(outputPath, state);
+
+  const verification = options.verifyWithPencil
+    ? verifyPenFileWithPencil(outputPath, {
+        pencilBin: options.pencilBin,
+        expectedTopLevelIds: document.children.map((node) => node.id)
+      })
+    : null;
+
+  return {
+    outputPath,
+    created,
+    document,
+    verification,
+    state,
+    statePath
+  };
+}
+
+function hashPayloadFiles(options) {
+  const nodes = readJsonPayload(options.nodesFile);
+  const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
+  const document = buildPenDocument({
+    version: options.version || DEFAULT_PEN_VERSION,
+    nodes,
+    variables
+  });
+
+  return {
+    document,
+    snapshotHash: hashPenDocument(document)
+  };
+}
+
+function comparePenSync(options) {
+  const penPath = path.resolve(options.penPath);
+  if (!fs.existsSync(penPath)) {
+    throw new Error(`Registered .pen file does not exist: ${penPath}`);
+  }
+
+  const persistedDocument = readPenDocument(penPath);
+  const live = hashPayloadFiles({
+    ...options,
+    version: options.version || persistedDocument.version || DEFAULT_PEN_VERSION
+  });
+  const persistedState = readPenState(penPath);
+  const persistedHash = persistedState && persistedState.snapshotHash
+    ? String(persistedState.snapshotHash)
+    : hashPenDocument(persistedDocument);
+
+  return {
+    penPath,
+    statePath: getStandardPenStatePath(penPath),
+    persistedHash,
+    liveHash: live.snapshotHash,
+    inSync: persistedHash === live.snapshotHash,
+    usedStateFile: Boolean(persistedState && persistedState.snapshotHash),
+    state: persistedState
   };
 }
 
@@ -316,11 +494,22 @@ module.exports = {
   readJsonPayload,
   normalizeNodesPayload,
   normalizeVariablesPayload,
+  canonicalizeJson,
   buildPenDocument,
+  hashPenDocument,
+  getStandardPenStatePath,
   writePenDocumentAtomic,
+  writeJsonFileAtomic,
+  buildPenState,
+  writePenStateAtomic,
+  readPenState,
   runPencilInteractive,
   verifyPenFileWithPencil,
   writePenFromPayloadFiles,
   capturePenSnapshot,
-  snapshotPenFile
+  snapshotPenFile,
+  readPenDocument,
+  ensurePenFile,
+  hashPayloadFiles,
+  comparePenSync
 };

package/lib/pencil-lock.js

@@ -0,0 +1,128 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function getLockPath(options = {}) {
+  const homeDir = options.homeDir ? path.resolve(options.homeDir) : os.homedir();
+  return path.join(homeDir, ".da-vinci", "pencil-mcp.lock");
+}
+
+function readLock(lockPath) {
+  const resolvedLockPath = path.resolve(lockPath);
+  if (!fs.existsSync(resolvedLockPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(resolvedLockPath, "utf8"));
+}
+
+function writeLock(lockPath, payload) {
+  const resolvedLockPath = path.resolve(lockPath);
+  fs.mkdirSync(path.dirname(resolvedLockPath), { recursive: true });
+  const handle = fs.openSync(resolvedLockPath, "wx");
+
+  try {
+    fs.writeFileSync(handle, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function acquirePencilLock(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const owner = options.owner || path.basename(projectPath);
+  const waitMs = Number.isFinite(Number(options.waitMs)) ? Number(options.waitMs) : 0;
+  const pollIntervalMs = Math.max(50, Number(options.pollIntervalMs) || 100);
+  const lockPath = getLockPath(options);
+  const deadline = Date.now() + Math.max(0, waitMs);
+  const payload = {
+    schema: 1,
+    projectPath,
+    owner,
+    pid: process.pid,
+    acquiredAt: new Date().toISOString()
+  };
+
+  while (true) {
+    try {
+      writeLock(lockPath, payload);
+      return {
+        lockPath,
+        acquired: true,
+        alreadyHeld: false,
+        lock: payload
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+
+      const current = readLock(lockPath);
+      if (current && current.projectPath === projectPath) {
+        return {
+          lockPath,
+          acquired: true,
+          alreadyHeld: true,
+          lock: current
+        };
+      }
+
+      if (Date.now() >= deadline) {
+        const holder = current
+          ? `${current.projectPath} (owner: ${current.owner || "unknown"}, pid: ${current.pid || "unknown"})`
+          : "unknown holder";
+        throw new Error(`Pencil MCP lock is already held by ${holder}.`);
+      }
+
+      const sleepUntil = Date.now() + pollIntervalMs;
+      while (Date.now() < sleepUntil) {
+        // Busy wait to keep the CLI synchronous without additional runtime dependencies.
+      }
+    }
+  }
+}
+
+function releasePencilLock(options = {}) {
+  const projectPath = options.projectPath ? path.resolve(options.projectPath) : "";
+  const lockPath = getLockPath(options);
+  const current = readLock(lockPath);
+
+  if (!current) {
+    return {
+      lockPath,
+      released: false,
+      hadLock: false,
+      lock: null
+    };
+  }
+
+  if (projectPath && current.projectPath !== projectPath && !options.force) {
+    throw new Error(
+      `Pencil MCP lock is held by a different project: ${current.projectPath}`
+    );
+  }
+
+  fs.rmSync(lockPath, { force: true });
+  return {
+    lockPath,
+    released: true,
+    hadLock: true,
+    lock: current
+  };
+}
+
+function getPencilLockStatus(options = {}) {
+  const lockPath = getLockPath(options);
+  return {
+    lockPath,
+    lock: readLock(lockPath)
+  };
+}
+
+module.exports = {
+  getLockPath,
+  readLock,
+  acquirePencilLock,
+  releasePencilLock,
+  getPencilLockStatus
+};

package/lib/pencil-session.js

@@ -0,0 +1,229 @@
+const fs = require("fs");
+const path = require("path");
+const {
+  ensurePenFile,
+  writePenFromPayloadFiles,
+  comparePenSync,
+  writeJsonFileAtomic
+} = require("./pen-persistence");
+const {
+  acquirePencilLock,
+  releasePencilLock,
+  getPencilLockStatus
+} = require("./pencil-lock");
+
+function resolveProjectRoot(projectPath) {
+  return path.resolve(projectPath || process.cwd());
+}
+
+function getSessionStatePath(projectPath) {
+  return path.join(resolveProjectRoot(projectPath), ".da-vinci", "state", "pencil-session.json");
+}
+
+function readSessionState(projectPath) {
+  const sessionStatePath = getSessionStatePath(projectPath);
+  if (!fs.existsSync(sessionStatePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(sessionStatePath, "utf8"));
+}
+
+function writeSessionState(projectPath, payload) {
+  const sessionStatePath = getSessionStatePath(projectPath);
+  writeJsonFileAtomic(sessionStatePath, payload);
+  return sessionStatePath;
+}
+
+function buildSessionState(projectPath, payload) {
+  return {
+    schema: 1,
+    projectRoot: resolveProjectRoot(projectPath),
+    ...payload
+  };
+}
+
+function assertLockHeldByProject(projectPath, options = {}) {
+  const status = getPencilLockStatus(options);
+  const expectedProjectRoot = resolveProjectRoot(projectPath);
+
+  if (!status.lock) {
+    throw new Error("No Pencil MCP lock is currently held for this project.");
+  }
+
+  if (status.lock.projectPath !== expectedProjectRoot) {
+    throw new Error(
+      `Pencil MCP lock is held by a different project: ${status.lock.projectPath}`
+    );
+  }
+
+  return status;
+}
+
+function beginPencilSession(options) {
+  const projectRoot = resolveProjectRoot(options.projectPath);
+  const ensureResult = ensurePenFile({
+    outputPath: options.penPath,
+    version: options.version,
+    verifyWithPencil: options.verifyWithPencil,
+    pencilBin: options.pencilBin
+  });
+  const lockResult = acquirePencilLock({
+    projectPath: projectRoot,
+    owner: options.owner,
+    waitMs: options.waitMs,
+    homeDir: options.homeDir
+  });
+
+  const session = buildSessionState(projectRoot, {
+    status: "active",
+    beganAt: new Date().toISOString(),
+    penPath: path.resolve(options.penPath),
+    lockPath: lockResult.lockPath,
+    lockOwner: lockResult.lock.owner,
+    penStatePath: ensureResult.statePath,
+    lastPersistedHash: ensureResult.state.snapshotHash,
+    lastPersistedAt: ensureResult.state.persistedAt,
+    lastTopLevelCount: ensureResult.state.topLevelCount
+  });
+  const sessionStatePath = writeSessionState(projectRoot, session);
+
+  return {
+    projectRoot,
+    penPath: ensureResult.outputPath,
+    session,
+    sessionStatePath,
+    ensureResult,
+    lockResult
+  };
+}
+
+function persistPencilSession(options) {
+  const projectRoot = resolveProjectRoot(options.projectPath);
+  const session = readSessionState(projectRoot);
+  assertLockHeldByProject(projectRoot, { homeDir: options.homeDir });
+
+  if (!session) {
+    throw new Error("No Pencil session state exists for this project. Run `pencil-session begin` first.");
+  }
+
+  const resolvedPenPath = path.resolve(options.penPath || session.penPath || "");
+  if (!resolvedPenPath) {
+    throw new Error("A registered `.pen` path is required for session persistence.");
+  }
+
+  if (session.penPath && path.resolve(session.penPath) !== resolvedPenPath) {
+    throw new Error(
+      `Session is bound to ${session.penPath}, but persist was requested for ${resolvedPenPath}.`
+    );
+  }
+
+  const writeResult = writePenFromPayloadFiles({
+    outputPath: resolvedPenPath,
+    nodesFile: options.nodesFile,
+    variablesFile: options.variablesFile,
+    version: options.version,
+    verifyWithPencil: options.verifyWithPencil,
+    pencilBin: options.pencilBin
+  });
+  const syncResult = comparePenSync({
+    penPath: resolvedPenPath,
+    nodesFile: options.nodesFile,
+    variablesFile: options.variablesFile,
+    version: options.version
+  });
+
+  const updatedSession = buildSessionState(projectRoot, {
+    ...session,
+    status: "active",
+    penPath: resolvedPenPath,
+    penStatePath: writeResult.statePath,
+    lastPersistedHash: writeResult.state.snapshotHash,
+    lastPersistedAt: writeResult.state.persistedAt,
+    lastTopLevelCount: writeResult.state.topLevelCount,
+    lastSyncVerifiedAt: new Date().toISOString(),
+    inSync: syncResult.inSync
+  });
+  const sessionStatePath = writeSessionState(projectRoot, updatedSession);
+
+  return {
+    projectRoot,
+    penPath: resolvedPenPath,
+    session: updatedSession,
+    sessionStatePath,
+    writeResult,
+    syncResult
+  };
+}
+
+function endPencilSession(options) {
+  const projectRoot = resolveProjectRoot(options.projectPath);
+  const session = readSessionState(projectRoot);
+
+  if (!session) {
+    throw new Error("No Pencil session state exists for this project. Run `pencil-session begin` first.");
+  }
+
+  const resolvedPenPath = path.resolve(options.penPath || session.penPath || "");
+  if (!resolvedPenPath) {
+    throw new Error("A registered `.pen` path is required for session shutdown.");
+  }
+
+  let syncResult = null;
+  if (options.nodesFile) {
+    syncResult = comparePenSync({
+      penPath: resolvedPenPath,
+      nodesFile: options.nodesFile,
+      variablesFile: options.variablesFile,
+      version: options.version
+    });
+
+    if (!syncResult.inSync) {
+      throw new Error("Cannot end Pencil session while the live MCP snapshot is out of sync with disk.");
+    }
+  }
+
+  const releaseResult = releasePencilLock({
+    projectPath: projectRoot,
+    homeDir: options.homeDir,
+    force: options.force
+  });
+
+  const updatedSession = buildSessionState(projectRoot, {
+    ...session,
+    status: "closed",
+    penPath: resolvedPenPath,
+    endedAt: new Date().toISOString(),
+    lastSyncVerifiedAt: syncResult ? new Date().toISOString() : session.lastSyncVerifiedAt || null,
+    inSync: syncResult ? syncResult.inSync : session.inSync === true
+  });
+  const sessionStatePath = writeSessionState(projectRoot, updatedSession);
+
+  return {
+    projectRoot,
+    penPath: resolvedPenPath,
+    session: updatedSession,
+    sessionStatePath,
+    syncResult,
+    releaseResult
+  };
+}
+
+function getPencilSessionStatus(options = {}) {
+  const projectRoot = resolveProjectRoot(options.projectPath);
+  return {
+    projectRoot,
+    sessionStatePath: getSessionStatePath(projectRoot),
+    session: readSessionState(projectRoot),
+    lockStatus: getPencilLockStatus({ homeDir: options.homeDir })
+  };
+}
+
+module.exports = {
+  getSessionStatePath,
+  readSessionState,
+  writeSessionState,
+  beginPencilSession,
+  persistPencilSession,
+  endPencilSession,
+  getPencilSessionStatus
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"
@@ -23,6 +23,8 @@
     "postinstall": "node scripts/postinstall.js",
     "validate-assets": "node scripts/validate-assets.js",
     "test:mcp-runtime-gate": "node scripts/test-mcp-runtime-gate.js",
+    "test:persistence-flows": "node scripts/test-persistence-flows.js",
+    "test:pencil-session": "node scripts/test-pencil-session.js",
     "test:pencil-preflight": "node scripts/test-pencil-preflight.js",
     "test:pen-persistence": "node scripts/test-pen-persistence.js"
   },

package/references/checkpoints.md

@@ -146,8 +146,9 @@ Check:
 - when shell access is available, `da-vinci audit --mode integrity <project-path>` ran after the first successful Pencil write and before broad expansion moved past the first approved anchor
 - if Pencil MCP only exposed a live document, the workflow reconstructed and wrote the registered project-local `.pen` file from MCP-readable document data before continuing
 - the workflow did not treat headless interactive `save()` alone as sufficient persistence evidence; the registered `.pen` was written from MCP-readable snapshot data or other verified filesystem truth
-- if no registered project-local `.pen` existed at the start of the redesign pass, the first approved live snapshot was written to the registered path before broad expansion continued
+- if no registered project-local `.pen` existed at the start of the redesign pass, the workflow seeded the registered `.pen` before the first Pencil edit and kept later live work bound to that path
 - if a registered project-local `.pen` already existed, material live edits were persisted back to that same path from the current MCP snapshot before the workflow claimed the design source was up to date
+- the current live Pencil snapshot hash matches the last persisted project-local `.pen` snapshot hash before completion claims
 - `.da-vinci/designs/` is being used cleanly for project-local `.pen` files rather than mixed with workflow markdown, screenshots, or other exports
 - exported screenshots are stored under `.da-vinci/changes/<change-id>/exports/` and are not being used as a substitute for the `.pen` source
 - `design-registry.md`, `pencil-design.md`, and `pencil-bindings.md` describe the same active project-local `.pen` source clearly enough to map and implement from
@@ -169,7 +170,9 @@ Run inside the active design session when Pencil MCP is available:
 Check:
 
 - the active editor is not still an unnamed live document such as `new`
+- the workflow did not keep using an empty `filePath` after a registered `.pen` existed
 - the active editor, registered project-local `.pen` path, and shell-visible `.pen` file are converged strongly enough to trust the runtime source
+- completion-stage runtime evidence includes an explicit live-to-disk sync verification for the registered `.pen`
 - claimed anchor ids exist in the active live editor
 - claimed reviewed screens and screenshot targets exist in the active live editor
 - screenshot-reviewed surfaces were not treated as approved while blocker-level review findings were ignored
@@ -184,7 +187,9 @@ Result meanings:
 Automatic failures:
 
 - if the active editor is still `new`, treat the runtime gate as `BLOCK`
+- if a registered `.pen` exists but Pencil writes still used an empty `filePath`, treat the runtime gate as `BLOCK`
 - if live anchor surfaces exist only in the current editor while no shell-visible `.pen` exists, treat the runtime gate as `BLOCK`
+- if the current live snapshot hash differs from the last persisted `.pen` snapshot hash at completion stage, treat the runtime gate as `BLOCK`
 - if claimed anchor ids, reviewed screen ids, or screenshot targets do not resolve in the active editor, treat the runtime gate as `BLOCK`
 - if blocker-level review findings were ignored while the workflow still approved the surface, treat the runtime gate as `BLOCK`
 - if the workflow presents no structured screenshot-review status or issue list for the approved surfaces, treat the runtime gate as `BLOCK`

package/references/pencil-design-to-code.md

@@ -68,12 +68,19 @@ When generating or editing Pencil data:
 - prefer 12 or fewer operations on anchor surfaces; after two failed batches on the same anchor, drop to micro-batches of 6 or fewer operations until a clean pass lands
 - if unsupported-property rollbacks repeat on the same anchor surface, stop treating that pass as stable forward progress until the schema usage is corrected
 - after any rolled-back batch or structure-changing edit, refresh the live node structure before descendant-targeted follow-up operations
+- before the first Pencil edit on a redesign pass, ensure the registered project-local `.pen` exists with `da-vinci ensure-pen --output <path> --verify-open`, then open that exact path instead of working in `new`
+- acquire the global Pencil lock before MCP write operations when multiple redesign sessions could overlap on the same machine
+- prefer the higher-level wrapper:
+  `da-vinci pencil-session begin`
+  `da-vinci pencil-session persist`
+  `da-vinci pencil-session end`
 - verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
 - do not treat headless interactive `save()` as authoritative persistence; write the project-local `.pen` from MCP-readable snapshot data instead
-- if no registered project-local `.pen` existed at the start of the session, let the first approved anchor surface happen in the live editor, then persist that first approved MCP snapshot under `.da-vinci/designs/`
 - if a registered project-local `.pen` already existed, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
 - use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` when you already have MCP-readable snapshot payloads and need an atomic project-local `.pen` write
-- use `da-vinci snapshot-pen --input <path> --output <path> --verify-open` when a project-local `.pen` already exists and you need to re-canonicalize it from a fresh MCP-readable snapshot
+- run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` after material live edits and before completion claims to prove the live snapshot matches the persisted `.pen`
+- use `da-vinci snapshot-pen --input <path> --output <path> --verify-open` only as a disk-to-disk utility when you need to re-canonicalize an existing `.pen`; it is not a substitute for persisting the current live editor
+- completion audit expects `.da-vinci/state/pencil-session.json` to exist and reflect the latest persisted `.pen` hash
 - keep workflow markdown out of `.da-vinci/designs/`; reserve that directory for `.pen` files only
 - keep screenshot exports out of `.da-vinci/designs/`; write them under `.da-vinci/changes/<change-id>/exports/`
 - after the first approved anchor surfaces, extract a shared primitive family before broad page expansion