@curdx/flow 2.3.5 → 2.3.7

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.3.5"
+    "version": "2.3.7"
   },
   "allowCrossMarketplaceDependenciesOn": [
     "context7-marketplace"
@@ -16,7 +16,7 @@
       "name": "curdx-flow",
       "source": "./",
       "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-      "version": "2.3.5",
+      "version": "2.3.7",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.3.7
+
+- taught `doctor` to detect source/package-vs-installed plugin version drift so local plugin development and release validation no longer silently run against stale Claude plugin cache state
+- exposed bundled plugin body version in the runtime report and machine-readable doctor payload for automation consumers
+- documented the reinstall/restart recovery path when Claude is still loading an older CurDX-Flow build
+
+## 2.3.6
+
+- taught `doctor` to inspect file-based Claude Code managed settings and apply them at the correct highest-precedence layer for CurDX-Flow plugin options
+- upgraded the `doctor --json` contract to v2 so wrappers can distinguish inspected `managed-file` scope from uninspected server-managed / MDM / CLI overrides
+- added report and workflow coverage for managed-settings fragments, invalid managed JSON, and managed-vs-local/project/user precedence
+
 ## 2.3.5
 
 - added a versioned `doctor --json` contract for CI/wrappers, including applied-fix metadata and explicit settings-inspection scope metadata

package/README.md

@@ -21,7 +21,8 @@ npx @curdx/flow install --all
 Requires modern Claude Code and Node 18+. The install flow registers the plugin,
 required reasoning/doc tools, and recommended companion plugins. Run
 `npx @curdx/flow doctor` after install if anything looks off. For CI or wrapper
-automation, use `npx @curdx/flow doctor --json`.
+automation, use `npx @curdx/flow doctor --json`, which now includes file-based
+managed settings in its inspected precedence model.
 
 After restart, CurDX-Flow routes the main thread through `flow-orchestrator`
 by default and starts the bundled `.flow` progress monitor in interactive

package/cli/README.md

@@ -42,7 +42,9 @@ External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plug
 
 `--fix` applies the safe automatic repairs the CLI can perform without guessing — currently the `bun` / `uv` PATH symlinks used by `claude-mem`. Everything else remains diagnostic-only.
 
-`--json` emits the full health result as machine-readable JSON for CI, wrappers, or external diagnostics. It includes `contractVersion`, `metadata.appliedFixes`, settings inspection scope metadata, the rendered report structure, and raw `doctorData`, including CurDX-Flow plugin option precedence and runtime env projection.
+`--json` emits the full health result as machine-readable JSON for CI, wrappers, or external diagnostics. It includes `contractVersion`, `metadata.appliedFixes`, settings inspection scope metadata, the rendered report structure, and raw `doctorData`, including CurDX-Flow plugin option precedence, file-based managed settings, and runtime env projection.
+
+`doctor` also compares the plugin body shipped with the current CLI/package against the `curdx-flow` version Claude actually has installed, so local development and release validation do not silently run against stale plugin cache state.
 
 ### Project initialization (not a CLI command)
 

package/cli/doctor-workflow.js

@@ -21,10 +21,10 @@ export { readProjectClaudeSettings };
 export { inspectRuntimeEnvironment };
 
 const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
-export const DOCTOR_JSON_CONTRACT_VERSION = 1;
+export const DOCTOR_JSON_CONTRACT_VERSION = 2;
 export const DOCTOR_SETTINGS_INSPECTION = Object.freeze({
-  pluginOptionScopesInspected: ["user", "project", "local"],
-  pluginOptionScopesNotInspected: ["managed", "cli"],
+  pluginOptionScopesInspected: ["managed-file", "user", "project", "local"],
+  pluginOptionScopesNotInspected: ["managed-server", "managed-mdm", "cli"],
 });
 
 export function createDoctorContext(args = []) {
@@ -163,9 +163,12 @@ export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROO
   const pluginSettingsPath = path.join(packageRoot, "settings.json");
   const pluginManifestPath = path.join(packageRoot, ".claude-plugin", "plugin.json");
   const monitorsPath = path.join(packageRoot, "monitors", "monitors.json");
+  const packageJsonPath = path.join(packageRoot, "package.json");
 
   const state = {
     exists: false,
+    packageVersion: null,
+    pluginVersion: null,
     defaultAgent: null,
     subagentStatusLineCommand: null,
     monitorCount: 0,
@@ -189,6 +192,13 @@ export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROO
     pluginManifest = null;
   }
 
+  try {
+    const pkg = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
+    state.packageVersion = typeof pkg?.version === "string" ? pkg.version : null;
+  } catch {
+    state.packageVersion = null;
+  }
+
   try {
     monitors = JSON.parse(await fs.readFile(monitorsPath, "utf-8"));
   } catch {
@@ -200,6 +210,7 @@ export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROO
   }
 
   state.exists = true;
+  state.pluginVersion = typeof pluginManifest?.version === "string" ? pluginManifest.version : null;
   state.defaultAgent = typeof pluginSettings?.agent === "string" ? pluginSettings.agent : null;
   state.subagentStatusLineCommand =
     typeof pluginSettings?.subagentStatusLine?.command === "string"

package/cli/lib/doctor-claude-settings.js

@@ -139,6 +139,22 @@ export const CURDX_FLOW_RUNTIME_CONSUMERS = {
   },
 };
 
+function resolveManagedSettingsRoot({ platform = process.platform, env = process.env } = {}) {
+  if (platform === "darwin") {
+    return "/Library/Application Support/ClaudeCode";
+  }
+
+  if (platform === "linux") {
+    return "/etc/claude-code";
+  }
+
+  if (platform === "win32") {
+    return path.join(env.ProgramFiles || "C:\\Program Files", "ClaudeCode");
+  }
+
+  return null;
+}
+
 function envFlagEnabled(value) {
   if (value === true || value === 1) return true;
   if (typeof value !== "string") return false;
@@ -226,6 +242,10 @@ function createCurdxFlowPluginOptionsState() {
   return {
     pluginId: CURDX_FLOW_PLUGIN_ID,
     definitions,
+    managed: {
+      overrides: {},
+      files: [],
+    },
     user: {
       pluginConfigsPresent: false,
       pluginConfigPresent: false,
@@ -250,12 +270,14 @@ function createCurdxFlowPluginOptionsState() {
 }
 
 function pluginScopeLabel(scope) {
+  if (scope === "managed") return "managed settings";
   if (scope === "local") return "settings.local.json";
   if (scope === "user") return "~/.claude/settings.json";
   return "settings.json";
 }
 
 function invalidSettingKindForScope(scope) {
+  if (scope === "managed") return "invalid-managed-setting";
   if (scope === "local") return "invalid-local-setting";
   if (scope === "user") return "invalid-user-setting";
   return "invalid-project-setting";
@@ -312,17 +334,23 @@ function buildCurdxFlowRuntimeProjection(pluginOptionsState) {
   });
 }
 
-function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope = "project") {
+function auditCurdxFlowPluginOptions(
+  parsed,
+  warnings,
+  pluginOptionsState,
+  { scope = "project", settingsLabel = pluginScopeLabel(scope), targetOverrides = null } = {}
+) {
   if (!isNonArrayObject(parsed) || !("pluginConfigs" in parsed)) {
     return;
   }
 
-  const target = scope === "local"
-    ? pluginOptionsState.local
-    : scope === "user"
-      ? pluginOptionsState.user
-      : pluginOptionsState.project;
-  const settingsLabel = pluginScopeLabel(scope);
+  const target = scope === "managed"
+    ? pluginOptionsState.managed
+    : scope === "local"
+      ? pluginOptionsState.local
+      : scope === "user"
+        ? pluginOptionsState.user
+        : pluginOptionsState.project;
   target.pluginConfigsPresent = true;
 
   if (!isNonArrayObject(parsed.pluginConfigs)) {
@@ -433,11 +461,107 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
       }
     }
 
-    target.overrides[key] = value;
+    const overrideTarget = targetOverrides || target.overrides;
+    overrideTarget[key] = value;
+    if (scope === "managed") {
+      target.overrides[key] = value;
+    }
     applyCurdxFlowPluginOptionOverride(pluginOptionsState, key, value, scope);
   }
 }
 
+async function readManagedClaudeSettings(
+  pluginOptionsState,
+  warnings,
+  {
+    platform = process.platform,
+    env = process.env,
+    managedSettingsDir = resolveManagedSettingsRoot({ platform, env }),
+  } = {}
+) {
+  const state = {
+    supported: Boolean(managedSettingsDir),
+    rootPath: managedSettingsDir,
+    basePath: managedSettingsDir ? path.join(managedSettingsDir, "managed-settings.json") : null,
+    dropInPath: managedSettingsDir ? path.join(managedSettingsDir, "managed-settings.d") : null,
+    exists: false,
+    baseExists: false,
+    dropInDirExists: false,
+    files: [],
+  };
+
+  if (!managedSettingsDir) {
+    return state;
+  }
+
+  const fileQueue = [];
+
+  try {
+    const stat = await fs.stat(state.basePath);
+    if (stat.isFile()) {
+      state.baseExists = true;
+      state.exists = true;
+      fileQueue.push({
+        label: "managed-settings.json",
+        path: state.basePath,
+      });
+    }
+  } catch {}
+
+  try {
+    const stat = await fs.stat(state.dropInPath);
+    if (stat.isDirectory()) {
+      state.dropInDirExists = true;
+      const entries = (await fs.readdir(state.dropInPath))
+        .filter((name) => !name.startsWith(".") && name.endsWith(".json"))
+        .sort();
+      for (const name of entries) {
+        const absPath = path.join(state.dropInPath, name);
+        const entryStat = await fs.stat(absPath);
+        if (!entryStat.isFile()) continue;
+        state.exists = true;
+        fileQueue.push({
+          label: `managed-settings.d/${name}`,
+          path: absPath,
+        });
+      }
+    }
+  } catch {}
+
+  for (const file of fileQueue) {
+    const entry = {
+      label: file.label,
+      path: file.path,
+      invalid: false,
+      parseError: null,
+      overrides: {},
+    };
+
+    try {
+      const parsed = JSON.parse(await fs.readFile(file.path, "utf-8"));
+      auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, {
+        scope: "managed",
+        settingsLabel: file.label,
+        targetOverrides: entry.overrides,
+      });
+    } catch (error) {
+      entry.invalid = true;
+      entry.parseError = error?.message || String(error);
+    }
+
+    state.files.push(entry);
+    pluginOptionsState.managed.files.push({
+      label: entry.label,
+      path: entry.path,
+      overrides: { ...entry.overrides },
+      invalid: entry.invalid,
+      parseError: entry.parseError,
+    });
+  }
+
+  return state;
+}
+
 function auditLocalClaudeSettings(parsed, warnings) {
   const scope = "local";
   const permissions = parsed?.permissions && typeof parsed.permissions === "object"
@@ -629,11 +753,30 @@ function auditLocalClaudeSettings(parsed, warnings) {
   }
 }
 
-export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir = os.homedir() } = {}) {
+export async function readProjectClaudeSettings(
+  cwd = process.cwd(),
+  {
+    homeDir = os.homedir(),
+    platform = process.platform,
+    env = process.env,
+    managedSettingsDir = resolveManagedSettingsRoot({ platform, env }),
+  } = {}
+) {
   const settingsPath = path.join(cwd, ".claude", "settings.json");
   const localSettingsPath = path.join(cwd, ".claude", "settings.local.json");
   const userSettingsPath = path.join(homeDir, ".claude", "settings.json");
   const state = {
+    managedSettings: {
+      supported: Boolean(managedSettingsDir),
+      rootPath: managedSettingsDir,
+      basePath: managedSettingsDir ? path.join(managedSettingsDir, "managed-settings.json") : null,
+      dropInPath: managedSettingsDir ? path.join(managedSettingsDir, "managed-settings.d") : null,
+      exists: false,
+      baseExists: false,
+      dropInDirExists: false,
+      files: [],
+    },
+    managedWarnings: [],
     userExists: false,
     userInvalid: false,
     userParseError: null,
@@ -667,7 +810,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
   if (state.userExists) {
     try {
       const userParsed = JSON.parse(await fs.readFile(userSettingsPath, "utf-8"));
-      auditCurdxFlowPluginOptions(userParsed, state.userWarnings, state.pluginOptions, "user");
+      auditCurdxFlowPluginOptions(userParsed, state.userWarnings, state.pluginOptions, { scope: "user" });
     } catch (error) {
       state.userInvalid = true;
       state.userParseError = error?.message || String(error);
@@ -698,7 +841,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
     const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
     const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
 
-    auditCurdxFlowPluginOptions(parsed, state.warnings, state.pluginOptions, "project");
+    auditCurdxFlowPluginOptions(parsed, state.warnings, state.pluginOptions, { scope: "project" });
 
     if ("enabledPlugins" in parsed && (
       !parsed.enabledPlugins ||
@@ -1019,7 +1162,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
   if (state.localExists) {
     try {
       const localParsed = JSON.parse(await fs.readFile(localSettingsPath, "utf-8"));
-      auditCurdxFlowPluginOptions(localParsed, state.localWarnings, state.pluginOptions, "local");
+      auditCurdxFlowPluginOptions(localParsed, state.localWarnings, state.pluginOptions, { scope: "local" });
       auditLocalClaudeSettings(localParsed, state.localWarnings);
     } catch (error) {
       state.localInvalid = true;
@@ -1027,6 +1170,16 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
     }
   }
 
+  state.managedSettings = await readManagedClaudeSettings(
+    state.pluginOptions,
+    state.managedWarnings,
+    {
+      platform,
+      env,
+      managedSettingsDir,
+    }
+  );
+
   state.pluginRuntimeProjection = buildCurdxFlowRuntimeProjection(state.pluginOptions);
 
   return state;

package/cli/lib/doctor-report.js

@@ -13,6 +13,27 @@ function pluginErrorDetails(plugin) {
 }
 
 function projectSettingsWarningDetails(warning) {
+  if (warning?.scope === "managed") {
+    if (warning.kind === "unknown-plugin-option") {
+      return [
+        "file-based managed settings override user, project, and local CurDX-Flow plugin options on this machine",
+        "remove the unknown key or rename it to a supported CurDX-Flow plugin option under pluginConfigs[curdx-flow@curdx-flow-marketplace].options",
+      ];
+    }
+
+    if (warning.kind === "invalid-managed-setting") {
+      return [
+        "file-based managed settings are evaluated before user/project/local settings",
+        "fix the managed JSON value shape so CurDX-Flow runtime projection matches the intended policy",
+      ];
+    }
+
+    return [
+      "file-based managed settings override user, project, and local CurDX-Flow plugin options on this machine",
+      "fix the managed policy or move the value to a supported CurDX-Flow plugin option key",
+    ];
+  }
+
   if (warning?.scope === "user") {
     if (warning.kind === "unknown-plugin-option") {
       return [
@@ -242,9 +263,23 @@ export function buildDoctorReport({
   pushLine(lines, "ok", `Node                  ${nodeVersion}`);
 
   const curdx = plugins.find((plugin) => plugin.name === "curdx-flow");
+  const bundledVersion =
+    bundledPluginRuntimeDefaults?.pluginVersion || bundledPluginRuntimeDefaults?.packageVersion || null;
   if (curdx) {
     if (curdx.status === "enabled") {
       pushLine(lines, "ok", `curdx-flow            v${curdx.version} (enabled)`);
+      if (bundledVersion && curdx.version && curdx.version !== bundledVersion) {
+        pushLine(
+          lines,
+          "warn",
+          `curdx-flow source/body  v${bundledVersion} differs from installed v${curdx.version}`,
+          [
+            "you are not validating the same CurDX-Flow build that Claude currently loads",
+            "reinstall the plugin from the current source/package, then restart Claude Code",
+            "run: npx @curdx/flow install --all",
+          ]
+        );
+      }
     } else {
       pushLine(
         lines,
@@ -421,6 +456,14 @@ export function buildDoctorReport({
   if (bundledPluginRuntimeDefaults?.exists) {
     const bundledRuntimeSection = createSection("CurDX-Flow bundled runtime:");
 
+    if (bundledVersion) {
+      pushSectionLine(
+        bundledRuntimeSection,
+        "info",
+        `Bundled plugin body    v${bundledVersion}`
+      );
+    }
+
     if (bundledPluginRuntimeDefaults.defaultAgent) {
       pushSectionLine(
         bundledRuntimeSection,
@@ -481,6 +524,7 @@ export function buildDoctorReport({
   ) {
     const configuredOptionsSection = createSection("CurDX-Flow configured options:");
     const optionState = projectClaudeSettings?.pluginOptions;
+    const managedOverrides = optionState?.managed?.overrides || {};
     const userOverrides = optionState?.user?.overrides || {};
     const projectOverrides = optionState?.project?.overrides || {};
     const localOverrides = optionState?.local?.overrides || {};
@@ -492,13 +536,42 @@ export function buildDoctorReport({
     pushSectionLine(
       configuredOptionsSection,
       "info",
-      "Scope precedence      settings.local.json > settings.json > ~/.claude/settings.json > bundled default",
+      "Scope precedence      file-managed > settings.local.json > settings.json > ~/.claude/settings.json > bundled default",
       [
-        "managed settings and command-line overrides are not inspected here",
+        "server-managed settings, MDM/registry policies, and command-line overrides are not inspected here",
         "effective values below reflect this machine only",
       ]
     );
 
+    if (projectClaudeSettings?.managedSettings?.exists) {
+      if (Object.keys(managedOverrides).length > 0) {
+        const summary = Object.entries(managedOverrides)
+          .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
+          .join(", ");
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          `file-managed settings ${Object.keys(managedOverrides).length} valid override(s)`,
+          [
+            summary,
+            projectClaudeSettings.managedSettings.rootPath,
+          ]
+        );
+      } else {
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          "file-managed settings present without valid CurDX-Flow overrides"
+        );
+      }
+    } else {
+      pushSectionLine(
+        configuredOptionsSection,
+        "info",
+        "file-managed settings not present"
+      );
+    }
+
     if (projectClaudeSettings?.userExists) {
       if (Object.keys(userOverrides).length > 0) {
         const summary = Object.entries(userOverrides)
@@ -589,7 +662,9 @@ export function buildDoctorReport({
           ? "project"
           : effective.source === "user"
             ? "user"
-          : "bundled default";
+            : effective.source === "managed"
+              ? "managed"
+              : "bundled default";
       pushSectionLine(
         configuredOptionsSection,
         "ok",
@@ -608,7 +683,9 @@ export function buildDoctorReport({
           ? "project"
           : entry.source === "user"
             ? "user"
-            : "bundled default";
+            : entry.source === "managed"
+              ? "managed"
+              : "bundled default";
       pushSectionLine(
         runtimeProjectionSection,
         "info",
@@ -709,8 +786,66 @@ export function buildDoctorReport({
   }
 
   const projectSettingsSection = createSection("Project Claude settings:");
+  const managedSettingsSection = createSection("Managed Claude settings:");
   const userSettingsSection = createSection("User Claude settings:");
 
+  if (projectClaudeSettings?.managedSettings?.supported) {
+    if (projectClaudeSettings.managedSettings.exists) {
+      pushSectionLine(
+        managedSettingsSection,
+        "info",
+        "File-based managed settings detected",
+        [projectClaudeSettings.managedSettings.rootPath]
+      );
+
+      for (const file of projectClaudeSettings.managedSettings.files || []) {
+        if (file.invalid) {
+          pushSectionLine(
+            managedSettingsSection,
+            "err",
+            `${file.label} invalid JSON`,
+            [file.parseError]
+          );
+          continue;
+        }
+
+        if (Object.keys(file.overrides || {}).length > 0) {
+          const summary = Object.entries(file.overrides)
+            .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
+            .join(", ");
+          pushSectionLine(
+            managedSettingsSection,
+            "info",
+            `${file.label} ${Object.keys(file.overrides).length} CurDX-Flow override(s)`,
+            [summary]
+          );
+        } else {
+          pushSectionLine(
+            managedSettingsSection,
+            "ok",
+            `${file.label} present`
+          );
+        }
+      }
+
+      if ((projectClaudeSettings.managedWarnings || []).length > 0) {
+        pushSectionLine(managedSettingsSection, "warn", "Managed CurDX-Flow settings need review");
+        for (const warning of projectClaudeSettings.managedWarnings) {
+          pushSectionLine(
+            managedSettingsSection,
+            "warn",
+            warning.message,
+            projectSettingsWarningDetails(warning)
+          );
+        }
+      }
+    } else {
+      pushSectionLine(managedSettingsSection, "info", "File-based managed settings not present");
+    }
+  } else {
+    pushSectionLine(managedSettingsSection, "info", "File-based managed settings not supported on this platform");
+  }
+
   if (projectClaudeSettings?.userExists) {
     if (projectClaudeSettings.userInvalid) {
       pushSectionLine(

package/knowledge/claude-code-runtime-contracts.md

@@ -89,6 +89,7 @@ Guarded artifact targets:
   - `daily_dependency_check`: silences or enables the once-per-day recommended-plugin reminder.
   - `monitor_interval_seconds`: controls plugin monitor polling cadence.
 - `doctor` should explain both the machine-effective config value and the projected plugin subprocess env var for these knobs, since hook/monitor behavior depends on the env projection rather than direct JSON parsing.
+- Current `doctor` inspection includes file-based managed settings (`managed-settings.json` plus sorted `managed-settings.d/*.json` fragments) before local/project/user settings. It still cannot see server-managed settings, MDM/registry policy delivery, or one-off CLI overrides.
 
 ## Plugin Dependency Constraints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {