dotmd-cli 0.65.1 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.65.1",
+  "version": "0.66.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/doctor.mjs

@@ -8,6 +8,7 @@ import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { checkClaudeCommands, removeGeneratedSlashCommands } from './claude-commands.mjs';
+import { checkSkillDrift } from './skill-drift.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
@@ -191,6 +192,7 @@ function runDoctorProject(config, { json = false } = {}) {
   const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
   const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
   const { docsWithoutFrontmatter, planStatusGaps } = findWorkflowDrift(config);
+  const skillDriftWarnings = checkSkillDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
     packageDependency: depVersion,
@@ -198,6 +200,7 @@ function runDoctorProject(config, { json = false } = {}) {
     deprecatedCommandMentions,
     docsWithoutFrontmatter,
     planStatusGaps,
+    skillDriftWarnings,
   };
 
   if (json) {
@@ -226,6 +229,11 @@ function runDoctorProject(config, { json = false } = {}) {
   } else {
     process.stdout.write('- plan status vocab: ok\n');
   }
+  if (skillDriftWarnings.length) {
+    process.stdout.write(yellow(`- canonical workflow block: drifted — CLAUDE.md and the plugin SKILL.md teach different workflows. Reconcile the block between the \`dotmd:canonical-workflow\` markers in both files.`) + '\n');
+  } else {
+    process.stdout.write('- canonical workflow block: in sync\n');
+  }
   return result;
 }
 

package/src/index.mjs

@@ -7,6 +7,7 @@ import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalRef
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 import { checkGlossaryConfig } from './glossary-check.mjs';
+import { checkSkillDrift } from './skill-drift.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -135,6 +136,9 @@ export function buildIndex(config, opts = {}) {
 
     const glossaryWarnings = checkGlossaryConfig(config);
     warnings.push(...glossaryWarnings);
+
+    const skillDriftWarnings = checkSkillDrift(config);
+    warnings.push(...skillDriftWarnings);
   }
 
   return {

package/src/skill-drift.mjs

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// dotmd is a drift- and staleness-catcher that didn't, until now, catch drift
+// in its OWN plugin surface. Two canonical workflow-doc surfaces are kept in
+// lockstep by hand: the repo's CLAUDE.md (its own instructions) and the plugin
+// SKILL.md (what every OTHER repo's session learns the workflow from). CLAUDE.md
+// literally says "keep it in sync with the guidance below" — this guard makes
+// that lockstep mechanical instead of manual.
+//
+// The comparison unit is a marked block (not a fuzzy phrase heuristic):
+// deterministic, robust, and zero false positives. Each surface wraps the
+// irreducible workflow contract between the markers below; the guard extracts
+// both and compares them whitespace-tolerantly. Editing the contract in one
+// surface and forgetting the other is exactly what this catches.
+
+export const CANONICAL_MARKERS = {
+  start: '<!-- dotmd:canonical-workflow:start -->',
+  end: '<!-- dotmd:canonical-workflow:end -->',
+};
+
+const CLAUDE_MD = 'CLAUDE.md';
+const SKILL_MD = path.join('plugins', 'dotmd', 'skills', 'dotmd', 'SKILL.md');
+
+// Pull the inner text between the canonical markers. Returns null when the
+// markers are absent or malformed — callers treat null as "this surface doesn't
+// participate in the lockstep block", which is what keeps a user repo that has
+// its own CLAUDE.md (but never adopted the block) from ever tripping the guard.
+export function extractCanonicalBlock(text) {
+  if (typeof text !== 'string') return null;
+  const startIdx = text.indexOf(CANONICAL_MARKERS.start);
+  if (startIdx === -1) return null;
+  const afterStart = startIdx + CANONICAL_MARKERS.start.length;
+  const endIdx = text.indexOf(CANONICAL_MARKERS.end, afterStart);
+  if (endIdx === -1 || endIdx < afterStart) return null;
+  return text.slice(afterStart, endIdx);
+}
+
+// Whitespace-tolerant so a CRLF vs LF or a stray trailing space between the two
+// files isn't reported as drift — only meaningful content divergence is.
+function normalizeBlock(block) {
+  return block
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/\s+$/, ''))
+    .join('\n')
+    .trim();
+}
+
+function readIfPresent(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Guard: the canonical workflow block must stay identical across CLAUDE.md and
+// the plugin SKILL.md. Returns [] unless BOTH files exist AND BOTH carry the
+// block — so it only fires in a repo that has adopted the lockstep convention
+// (i.e. the dotmd repo itself), never in a user repo that merely has its own
+// CLAUDE.md. That strict gate is the price of zero false positives; the
+// trade-off is that deleting the markers from one surface silently disables the
+// guard rather than warning (a deliberate, visible act, unlike a content edit).
+export function checkSkillDrift(config) {
+  const repoRoot = config?.repoRoot;
+  if (!repoRoot) return [];
+
+  const claudeText = readIfPresent(path.join(repoRoot, CLAUDE_MD));
+  const skillText = readIfPresent(path.join(repoRoot, SKILL_MD));
+  if (claudeText === null || skillText === null) return [];
+
+  const claudeBlock = extractCanonicalBlock(claudeText);
+  const skillBlock = extractCanonicalBlock(skillText);
+  if (claudeBlock === null || skillBlock === null) return [];
+
+  if (normalizeBlock(claudeBlock) === normalizeBlock(skillBlock)) return [];
+
+  return [{
+    path: SKILL_MD,
+    level: 'warning',
+    message: `canonical workflow block drifted from \`${CLAUDE_MD}\`. The block between \`${CANONICAL_MARKERS.start}\` and \`${CANONICAL_MARKERS.end}\` must stay identical in both files — reconcile them so the plugin skill and the repo instructions teach the same workflow.`,
+  }];
+}