@curdx/flow 2.3.2 → 2.3.4

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.2"
+    "version": "2.3.4"
   },
   "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.2",
+      "version": "2.3.4",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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/cli/lib/doctor-claude-settings.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 
 const PROJECT_ONLY_IGNORED_SETTINGS = [
@@ -120,6 +121,23 @@ const CURDX_FLOW_REQUIRED_PLUGIN_IDS = ["context7-plugin@context7-marketplace"];
 const HTTP_HOOK_SETTINGS = ["allowedHttpHookUrls", "httpHookAllowedEnvVars"];
 const PERSISTED_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"];
 const ENV_EFFORT_LEVELS = [...PERSISTED_EFFORT_LEVELS, "max", "auto"];
+const CURDX_FLOW_RUNTIME_CONSUMERS = {
+  autonomous_blocking: {
+    envVar: "CLAUDE_PLUGIN_OPTION_AUTONOMOUS_BLOCKING",
+    consumer: "hooks/scripts/stop-watcher.sh",
+    summary: "controls whether the Stop hook blocks Claude from stopping while execute work remains",
+  },
+  daily_dependency_check: {
+    envVar: "CLAUDE_PLUGIN_OPTION_DAILY_DEPENDENCY_CHECK",
+    consumer: "hooks/scripts/session-start.sh",
+    summary: "controls the once-per-day recommended companion plugin reminder",
+  },
+  monitor_interval_seconds: {
+    envVar: "CLAUDE_PLUGIN_OPTION_MONITOR_INTERVAL_SECONDS",
+    consumer: "monitors/scripts/flow-state-monitor.sh",
+    summary: "controls the polling interval for the interactive flow-state monitor",
+  },
+};
 
 function envFlagEnabled(value) {
   if (value === true || value === 1) return true;
@@ -208,6 +226,12 @@ function createCurdxFlowPluginOptionsState() {
   return {
     pluginId: CURDX_FLOW_PLUGIN_ID,
     definitions,
+    user: {
+      pluginConfigsPresent: false,
+      pluginConfigPresent: false,
+      optionsPresent: false,
+      overrides: {},
+    },
     project: {
       pluginConfigsPresent: false,
       pluginConfigPresent: false,
@@ -221,11 +245,71 @@ function createCurdxFlowPluginOptionsState() {
       overrides: {},
     },
     repoEffective,
+    machineEffective: structuredClone(repoEffective),
   };
 }
 
 function pluginScopeLabel(scope) {
-  return scope === "local" ? "settings.local.json" : "settings.json";
+  if (scope === "local") return "settings.local.json";
+  if (scope === "user") return "~/.claude/settings.json";
+  return "settings.json";
+}
+
+function invalidSettingKindForScope(scope) {
+  if (scope === "local") return "invalid-local-setting";
+  if (scope === "user") return "invalid-user-setting";
+  return "invalid-project-setting";
+}
+
+function applyCurdxFlowPluginOptionOverride(pluginOptionsState, key, value, scope) {
+  pluginOptionsState.machineEffective[key] = {
+    value,
+    source: scope,
+  };
+
+  if (scope === "project" || scope === "local") {
+    pluginOptionsState.repoEffective[key] = {
+      value,
+      source: scope,
+    };
+  }
+}
+
+function buildCurdxFlowRuntimeProjection(pluginOptionsState) {
+  return pluginOptionsState.definitions.map((definition) => {
+    const effective = pluginOptionsState.machineEffective[definition.key] || {
+      value: definition.default,
+      source: "default",
+    };
+    const runtime = CURDX_FLOW_RUNTIME_CONSUMERS[definition.key] || {};
+    const details = [];
+
+    if (definition.key === "autonomous_blocking") {
+      details.push(
+        effective.value === false
+          ? "stop-hook continuation is disabled; Claude may stop at turn end even when execute tasks remain"
+          : "stop-hook continuation is enabled; CurDX-Flow can block turn end while execute tasks remain"
+      );
+    } else if (definition.key === "daily_dependency_check") {
+      details.push(
+        effective.value === false
+          ? "SessionStart plugin reminder is disabled on this machine"
+          : "SessionStart plugin reminder runs at most once per day on this machine"
+      );
+    } else if (definition.key === "monitor_interval_seconds") {
+      details.push(`flow-state monitor polls every ${effective.value} second(s) when Monitor is available`);
+    }
+
+    return {
+      key: definition.key,
+      envVar: runtime.envVar || `CLAUDE_PLUGIN_OPTION_${definition.key.toUpperCase()}`,
+      consumer: runtime.consumer || "plugin subprocess",
+      summary: runtime.summary || "runtime consumer",
+      value: effective.value,
+      source: effective.source,
+      details,
+    };
+  });
 }
 
 function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope = "project") {
@@ -233,14 +317,18 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
     return;
   }
 
-  const target = scope === "local" ? pluginOptionsState.local : pluginOptionsState.project;
+  const target = scope === "local"
+    ? pluginOptionsState.local
+    : scope === "user"
+      ? pluginOptionsState.user
+      : pluginOptionsState.project;
   const settingsLabel = pluginScopeLabel(scope);
   target.pluginConfigsPresent = true;
 
   if (!isNonArrayObject(parsed.pluginConfigs)) {
     pushScopedWarning(
       warnings,
-      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      invalidSettingKindForScope(scope),
       `pluginConfigs in ${settingsLabel} must be an object keyed by plugin@marketplace id`,
       scope
     );
@@ -257,7 +345,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
   if (!isNonArrayObject(pluginConfig)) {
     pushScopedWarning(
       warnings,
-      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      invalidSettingKindForScope(scope),
       `pluginConfigs[${CURDX_FLOW_PLUGIN_ID}] in ${settingsLabel} must be an object when set`,
       scope
     );
@@ -273,7 +361,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
   if (!isNonArrayObject(pluginConfig.options)) {
     pushScopedWarning(
       warnings,
-      scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+      invalidSettingKindForScope(scope),
       `pluginConfigs[${CURDX_FLOW_PLUGIN_ID}].options in ${settingsLabel} must be an object when set`,
       scope
     );
@@ -296,7 +384,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
     if (definition.type === "boolean" && typeof value !== "boolean") {
       pushScopedWarning(
         warnings,
-        scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+        invalidSettingKindForScope(scope),
         `CurDX-Flow plugin option ${key} in ${settingsLabel} must be boolean`,
         scope
       );
@@ -307,7 +395,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
       if (typeof value !== "number" || Number.isNaN(value)) {
         pushScopedWarning(
           warnings,
-          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          invalidSettingKindForScope(scope),
           `CurDX-Flow plugin option ${key} in ${settingsLabel} must be a number`,
           scope
         );
@@ -317,7 +405,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
       if (definition.integer && !Number.isInteger(value)) {
         pushScopedWarning(
           warnings,
-          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          invalidSettingKindForScope(scope),
           `CurDX-Flow plugin option ${key} in ${settingsLabel} must be an integer`,
           scope
         );
@@ -327,7 +415,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
       if (typeof definition.min === "number" && value < definition.min) {
         pushScopedWarning(
           warnings,
-          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          invalidSettingKindForScope(scope),
           `CurDX-Flow plugin option ${key} in ${settingsLabel} must be between ${definition.min} and ${definition.max}`,
           scope
         );
@@ -337,7 +425,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
       if (typeof definition.max === "number" && value > definition.max) {
         pushScopedWarning(
           warnings,
-          scope === "local" ? "invalid-local-setting" : "invalid-project-setting",
+          invalidSettingKindForScope(scope),
           `CurDX-Flow plugin option ${key} in ${settingsLabel} must be between ${definition.min} and ${definition.max}`,
           scope
         );
@@ -346,10 +434,7 @@ function auditCurdxFlowPluginOptions(parsed, warnings, pluginOptionsState, scope
     }
 
     target.overrides[key] = value;
-    pluginOptionsState.repoEffective[key] = {
-      value,
-      source: scope,
-    };
+    applyCurdxFlowPluginOptionOverride(pluginOptionsState, key, value, scope);
   }
 }
 
@@ -544,10 +629,15 @@ function auditLocalClaudeSettings(parsed, warnings) {
   }
 }
 
-export async function readProjectClaudeSettings(cwd = process.cwd()) {
+export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir = os.homedir() } = {}) {
   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 = {
+    userExists: false,
+    userInvalid: false,
+    userParseError: null,
+    userWarnings: [],
     exists: false,
     localExists: false,
     invalid: false,
@@ -557,8 +647,16 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
     localParseError: null,
     localWarnings: [],
     pluginOptions: createCurdxFlowPluginOptionsState(),
+    pluginRuntimeProjection: [],
   };
 
+  try {
+    const userStat = await fs.stat(userSettingsPath);
+    state.userExists = userStat.isFile();
+  } catch {
+    state.userExists = false;
+  }
+
   try {
     const localStat = await fs.stat(localSettingsPath);
     state.localExists = localStat.isFile();
@@ -566,6 +664,16 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
     state.localExists = false;
   }
 
+  if (state.userExists) {
+    try {
+      const userParsed = JSON.parse(await fs.readFile(userSettingsPath, "utf-8"));
+      auditCurdxFlowPluginOptions(userParsed, state.userWarnings, state.pluginOptions, "user");
+    } catch (error) {
+      state.userInvalid = true;
+      state.userParseError = error?.message || String(error);
+    }
+  }
+
   let parsed;
   try {
     const stat = await fs.stat(settingsPath);
@@ -919,5 +1027,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd()) {
     }
   }
 
+  state.pluginRuntimeProjection = buildCurdxFlowRuntimeProjection(state.pluginOptions);
+
   return state;
 }

package/cli/lib/doctor-report.js

@@ -13,6 +13,33 @@ function pluginErrorDetails(plugin) {
 }
 
 function projectSettingsWarningDetails(warning) {
+  if (warning?.scope === "user") {
+    if (warning.kind === "unknown-plugin-option") {
+      return [
+        "~/.claude/settings.json applies across all your repositories 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-user-setting" &&
+      (
+        warning.message?.includes("pluginConfigs[curdx-flow@curdx-flow-marketplace]") ||
+        warning.message?.includes("CurDX-Flow plugin option")
+      )
+    ) {
+      return [
+        "CurDX-Flow plugin options in ~/.claude/settings.json apply across all local repositories unless a project or local override wins",
+        "use boolean values for autonomous_blocking and daily_dependency_check, and keep monitor_interval_seconds as an integer between 3 and 60",
+      ];
+    }
+
+    return [
+      "~/.claude/settings.json applies across all your repositories on this machine",
+      "fix or remove the user-scoped override if CurDX-Flow behaves unexpectedly everywhere",
+    ];
+  }
+
   if (warning?.scope === "local") {
     if (warning.kind === "unknown-plugin-option") {
       return [
@@ -454,9 +481,10 @@ export function buildDoctorReport({
   ) {
     const configuredOptionsSection = createSection("CurDX-Flow configured options:");
     const optionState = projectClaudeSettings?.pluginOptions;
+    const userOverrides = optionState?.user?.overrides || {};
     const projectOverrides = optionState?.project?.overrides || {};
     const localOverrides = optionState?.local?.overrides || {};
-    const repoEffective = optionState?.repoEffective || {};
+    const machineEffective = optionState?.machineEffective || optionState?.repoEffective || {};
     const definitions = bundledPluginRuntimeDefaults?.userConfig?.length
       ? bundledPluginRuntimeDefaults.userConfig
       : (optionState?.definitions || []);
@@ -464,13 +492,42 @@ export function buildDoctorReport({
     pushSectionLine(
       configuredOptionsSection,
       "info",
-      "Scope precedence      settings.local.json > settings.json > bundled default",
+      "Scope precedence      settings.local.json > settings.json > ~/.claude/settings.json > bundled default",
       [
-        "this section audits repo-scoped CurDX-Flow plugin options only",
-        "user-level ~/.claude/settings.json is not inspected here",
+        "managed settings and command-line overrides are not inspected here",
+        "effective values below reflect this machine only",
       ]
     );
 
+    if (projectClaudeSettings?.userExists) {
+      if (Object.keys(userOverrides).length > 0) {
+        const summary = Object.entries(userOverrides)
+          .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
+          .join(", ");
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          `~/.claude/settings.json ${Object.keys(userOverrides).length} valid override(s)`,
+          [
+            summary,
+            "user-scoped overrides apply across repositories unless project/local settings win",
+          ]
+        );
+      } else {
+        pushSectionLine(
+          configuredOptionsSection,
+          "info",
+          "~/.claude/settings.json present without valid CurDX-Flow overrides"
+        );
+      }
+    } else {
+      pushSectionLine(
+        configuredOptionsSection,
+        "info",
+        "~/.claude/settings.json not present"
+      );
+    }
+
     if (Object.keys(projectOverrides).length > 0) {
       const summary = Object.entries(projectOverrides)
         .map(([key, value]) => `${key}=${formatInlineValue(value)}`)
@@ -522,7 +579,7 @@ export function buildDoctorReport({
     }
 
     for (const definition of definitions) {
-      const effective = repoEffective[definition.key] || {
+      const effective = machineEffective[definition.key] || {
         value: definition.default,
         source: "default",
       };
@@ -530,6 +587,8 @@ export function buildDoctorReport({
         ? "local"
         : effective.source === "project"
           ? "project"
+          : effective.source === "user"
+            ? "user"
           : "bundled default";
       pushSectionLine(
         configuredOptionsSection,
@@ -539,6 +598,30 @@ export function buildDoctorReport({
     }
   }
 
+  if ((projectClaudeSettings?.pluginRuntimeProjection || []).length > 0) {
+    const runtimeProjectionSection = createSection("CurDX-Flow runtime projection:");
+
+    for (const entry of projectClaudeSettings.pluginRuntimeProjection) {
+      const sourceLabel = entry.source === "local"
+        ? "local"
+        : entry.source === "project"
+          ? "project"
+          : entry.source === "user"
+            ? "user"
+            : "bundled default";
+      pushSectionLine(
+        runtimeProjectionSection,
+        "info",
+        `${entry.envVar.padEnd(36)} ${formatInlineValue(entry.value)} (${sourceLabel})`,
+        [
+          `consumer: ${entry.consumer}`,
+          entry.summary,
+          ...(entry.details || []),
+        ]
+      );
+    }
+  }
+
   const localProjectSection = createSection("Local project:");
   if (projectState?.exists) {
     pushSectionLine(localProjectSection, "ok", `.flow/                ${cwd}`);
@@ -626,6 +709,33 @@ export function buildDoctorReport({
   }
 
   const projectSettingsSection = createSection("Project Claude settings:");
+  const userSettingsSection = createSection("User Claude settings:");
+
+  if (projectClaudeSettings?.userExists) {
+    if (projectClaudeSettings.userInvalid) {
+      pushSectionLine(
+        userSettingsSection,
+        "err",
+        "~/.claude/settings.json invalid JSON",
+        [projectClaudeSettings.userParseError]
+      );
+    } else if ((projectClaudeSettings.userWarnings || []).length > 0) {
+      pushSectionLine(userSettingsSection, "warn", "~/.claude/settings.json affects CurDX-Flow globally");
+      for (const warning of projectClaudeSettings.userWarnings) {
+        pushSectionLine(
+          userSettingsSection,
+          "warn",
+          warning.message,
+          projectSettingsWarningDetails(warning)
+        );
+      }
+    } else {
+      pushSectionLine(userSettingsSection, "ok", "~/.claude/settings.json present");
+    }
+  } else {
+    pushSectionLine(userSettingsSection, "info", "~/.claude/settings.json not present");
+  }
+
   if (projectClaudeSettings?.exists) {
     if (projectClaudeSettings.invalid) {
       pushSectionLine(

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

@@ -88,6 +88,7 @@ Guarded artifact targets:
   - `autonomous_blocking`: lets users disable stop-hook continuation without editing plugin files.
   - `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.
 
 ## Plugin Dependency Constraints
 

package/package.json

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