@curdx/flow 2.3.3 → 2.3.5

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "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,11 @@
 # Changelog
 
+## 2.3.5
+
+- added a versioned `doctor --json` contract for CI/wrappers, including applied-fix metadata and explicit settings-inspection scope metadata
+- added CLI-level regression coverage so `doctor --json` stays silent except for JSON stdout and exit code
+- locked runtime env consumer drift checks against manifest `userConfig` keys and the actual bundled hook/monitor scripts
+
 ## 2.3.1
 
 - expanded `doctor` to report CurDX-Flow’s bundled main-thread agent, monitor surface, and plugin option defaults

package/README.md

@@ -20,7 +20,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.
+`npx @curdx/flow doctor` after install if anything looks off. For CI or wrapper
+automation, use `npx @curdx/flow doctor --json`.
 
 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

@@ -36,12 +36,14 @@ Steps:
 | `--all` | Install all recommended plugins, no prompt |
 | `--no-deps` | Install only curdx-flow itself |
 
-### `doctor [--verbose] [--fix]`
+### `doctor [--verbose] [--fix] [--json]`
 
 External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plugins / current directory `.flow/` state.
 
 `--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.
+
 ### Project initialization (not a CLI command)
 
 Project initialization is a Claude Code slash command, not a CLI one. After `install`, open your project in Claude Code and run:

package/cli/doctor-workflow.js

@@ -21,10 +21,16 @@ export { readProjectClaudeSettings };
 export { inspectRuntimeEnvironment };
 
 const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
+export const DOCTOR_JSON_CONTRACT_VERSION = 1;
+export const DOCTOR_SETTINGS_INSPECTION = Object.freeze({
+  pluginOptionScopesInspected: ["user", "project", "local"],
+  pluginOptionScopesNotInspected: ["managed", "cli"],
+});
 
 export function createDoctorContext(args = []) {
   return {
     fix: args.includes("--fix"),
+    json: args.includes("--json"),
     verbose: args.includes("--verbose") || args.includes("-v"),
   };
 }
@@ -334,6 +340,34 @@ export function renderReportLines(lines, { logImpl = log } = {}) {
   }
 }
 
+export function buildDoctorJsonPayload({
+  context = {},
+  doctorData,
+  fixes = [],
+  report,
+} = {}) {
+  return {
+    contractVersion: DOCTOR_JSON_CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    context: {
+      fix: context.fix === true,
+      json: context.json === true,
+      verbose: context.verbose === true,
+    },
+    summary: {
+      errors: report?.errors || 0,
+      warnings: report?.warnings || 0,
+      healthy: (report?.errors || 0) === 0,
+    },
+    metadata: {
+      appliedFixes: fixes,
+      settingsInspection: DOCTOR_SETTINGS_INSPECTION,
+    },
+    doctorData,
+    report,
+  };
+}
+
 export function printDoctorSummary(
   report,
   { logImpl = log, exitImpl = process.exit } = {}

package/cli/doctor.js

@@ -9,6 +9,7 @@ import {
 import { buildDoctorReport } from "./lib/doctor-report.js";
 import {
   applyDoctorFixes,
+  buildDoctorJsonPayload,
   collectDoctorData,
   createDoctorContext,
   printDoctorSummary,
@@ -16,29 +17,57 @@ import {
   renderReportLines,
 } from "./doctor-workflow.js";
 
-export async function doctor(args = []) {
-  const context = createDoctorContext(args);
+export async function doctor(
+  args = [],
+  {
+    applyDoctorFixesImpl = applyDoctorFixes,
+    buildDoctorJsonPayloadImpl = buildDoctorJsonPayload,
+    buildDoctorReportImpl = buildDoctorReport,
+    collectDoctorDataImpl = collectDoctorData,
+    createDoctorContextImpl = createDoctorContext,
+    printDoctorSummaryImpl = printDoctorSummary,
+    printVerboseDoctorDetailsImpl = printVerboseDoctorDetails,
+    renderReportLinesImpl = renderReportLines,
+    logImpl = log,
+    colorImpl = color,
+    consoleImpl = console,
+    processImpl = process,
+  } = {}
+) {
+  const context = createDoctorContextImpl(args);
+  let fixes = [];
 
-  log.title("🏥 CurdX-Flow Health Check");
+  if (!context.json) {
+    logImpl.title("🏥 CurdX-Flow Health Check");
+  }
 
-  const doctorData = await collectDoctorData();
+  const doctorData = await collectDoctorDataImpl();
   if (context.fix) {
-    log.info("Applying safe fixes...");
-    const fixes = await applyDoctorFixes(doctorData);
-    if (fixes.length === 0) {
-      log.info("No automatic fixes available for the current environment");
+    if (!context.json) {
+      logImpl.info("Applying safe fixes...");
+    }
+    fixes = await applyDoctorFixesImpl(doctorData);
+    if (fixes.length === 0 && !context.json) {
+      logImpl.info("No automatic fixes available for the current environment");
     }
   }
-  const report = buildDoctorReport(doctorData);
+  const report = buildDoctorReportImpl(doctorData);
+
+  if (context.json) {
+    const payload = buildDoctorJsonPayloadImpl({ context, doctorData, fixes, report });
+    consoleImpl.log(JSON.stringify(payload, null, 2));
+    processImpl.exitCode = report.errors > 0 ? 1 : 0;
+    return;
+  }
 
-  renderReportLines(report.lines);
+  renderReportLinesImpl(report.lines, { logImpl });
   for (const section of report.sections) {
-    console.log(`\n${color.bold(section.title)}`);
-    renderReportLines(section.lines);
+    consoleImpl.log(`\n${colorImpl.bold(section.title)}`);
+    renderReportLinesImpl(section.lines, { logImpl });
   }
 
-  printDoctorSummary(report);
+  printDoctorSummaryImpl(report, { logImpl });
   if (context.verbose && doctorData.claudeVersionValue) {
-    printVerboseDoctorDetails();
+    printVerboseDoctorDetailsImpl();
   }
 }

package/cli/help.js

@@ -18,6 +18,7 @@ ${color.bold("COMMANDS")}
 
   ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
             --fix            Apply safe runtime fixes (bun/uv PATH symlinks)
+            --json           Emit machine-readable health report JSON
             --verbose        Show raw plugin list details
 
   ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest

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

@@ -121,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"];
+export 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;
@@ -258,6 +275,43 @@ function applyCurdxFlowPluginOptionOverride(pluginOptionsState, key, value, scop
   }
 }
 
+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") {
   if (!isNonArrayObject(parsed) || !("pluginConfigs" in parsed)) {
     return;
@@ -593,6 +647,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
     localParseError: null,
     localWarnings: [],
     pluginOptions: createCurdxFlowPluginOptionsState(),
+    pluginRuntimeProjection: [],
   };
 
   try {
@@ -972,5 +1027,7 @@ export async function readProjectClaudeSettings(cwd = process.cwd(), { homeDir =
     }
   }
 
+  state.pluginRuntimeProjection = buildCurdxFlowRuntimeProjection(state.pluginOptions);
+
   return state;
 }

package/cli/lib/doctor-report.js

@@ -598,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}`);

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.3",
+  "version": "2.3.5",
   "description": "Skill-first discipline layer and CLI installer for Claude Code",
   "type": "module",
   "bin": {