@curdx/flow 2.3.8 → 2.3.10

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.8"
+    "version": "2.3.10"
   },
   "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.8",
+      "version": "2.3.10",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"
@@ -40,7 +40,6 @@
       "dependencies": [
         {
           "name": "context7-plugin",
-          "version": "^1.0.0",
           "marketplace": "context7-marketplace"
         }
       ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.3.8",
+  "version": "2.3.10",
   "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",
@@ -37,7 +37,6 @@
     "./agents/flow-ux-designer.md",
     "./agents/flow-verifier.md"
   ],
-  "hooks": "./hooks/hooks.json",
   "outputStyles": "./output-styles/",
   "monitors": "./monitors/monitors.json",
   "userConfig": {
@@ -65,7 +64,6 @@
   "dependencies": [
     {
       "name": "context7-plugin",
-      "version": "^1.0.0",
       "marketplace": "context7-marketplace"
     }
   ]

package/cli/doctor-workflow.js

@@ -2,7 +2,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { removeMcp } from "./lib/claude-ops.js";
 import { readProjectClaudeSettings } from "./lib/doctor-claude-settings.js";
+import { CONFIG_FILE, readConfig, writeConfig } from "./lib/config.js";
 import { inspectRuntimeEnvironment } from "./lib/doctor-runtime-environment.js";
 import {
   claudeVersion,
@@ -310,6 +312,7 @@ export async function collectDoctorData(
     readProjectTeamConfigImpl = readProjectTeamConfig,
     readProjectClaudeSettingsImpl = readProjectClaudeSettings,
     readBundledPluginRuntimeDefaultsImpl = readBundledPluginRuntimeDefaults,
+    readConfigImpl = readConfig,
   } = {}
 ) {
   const claudeVersionValue = claudeVersionImpl();
@@ -338,6 +341,10 @@ export async function collectDoctorData(
     projectTeamConfig: await readProjectTeamConfigImpl(cwd),
     projectClaudeSettings: await readProjectClaudeSettingsImpl(cwd),
     bundledPluginRuntimeDefaults: await readBundledPluginRuntimeDefaultsImpl(),
+    legacyInstallState: {
+      configPath: CONFIG_FILE,
+      hasLegacyContext7ApiKey: Object.prototype.hasOwnProperty.call(readConfigImpl(), "context7ApiKey"),
+    },
   };
 }
 
@@ -345,9 +352,47 @@ export async function applyDoctorFixes(
   doctorData,
   {
     ensureClaudeMemRuntimesImpl = ensureClaudeMemRuntimes,
+    removeMcpImpl = removeMcp,
+    readConfigImpl = readConfig,
+    writeConfigImpl = writeConfig,
   } = {}
 ) {
   const fixes = [];
+  const context7PluginOwnsMcp = doctorData.mcps.some(
+    (entry) => entry.name === "context7" && entry.plugin === "context7-plugin"
+  );
+  const hasLegacyUserContext7Mcp =
+    doctorData.userMcpConfig instanceof Map && doctorData.userMcpConfig.has("context7");
+
+  if (context7PluginOwnsMcp && hasLegacyUserContext7Mcp) {
+    const result = await removeMcpImpl({ name: "context7" });
+    if (result.code === 0) {
+      doctorData.userMcpConfig.delete("context7");
+      doctorData.mcps = doctorData.mcps.filter(
+        (entry) => !(entry.name === "context7" && entry.plugin == null)
+      );
+      fixes.push({
+        kind: "legacy-context7-user-mcp-removed",
+      });
+    }
+  }
+
+  if (doctorData.legacyInstallState?.hasLegacyContext7ApiKey) {
+    const config = readConfigImpl();
+    if (Object.prototype.hasOwnProperty.call(config, "context7ApiKey")) {
+      delete config.context7ApiKey;
+      writeConfigImpl(config);
+      doctorData.legacyInstallState = {
+        ...doctorData.legacyInstallState,
+        hasLegacyContext7ApiKey: false,
+      };
+      fixes.push({
+        kind: "legacy-context7-api-key-removed",
+        configPath: CONFIG_FILE,
+      });
+    }
+  }
+
   const claudeMemEnabled = doctorData.plugins.some(
     (plugin) => plugin.name === "claude-mem" && plugin.status === "enabled"
   );

package/cli/install-context7-config.js

@@ -1,97 +1,78 @@
 /**
- * Context7 API-key configuration during install. Private to the
- * required-plugins concern; not re-exported from install-companions.js.
+ * Reconcile legacy Context7 install state after the official plugin is
+ * installed. Private to the required-plugins concern; not re-exported from
+ * install-companions.js.
  */
 
-import { addMcp, removeMcp } from "./lib/claude-ops.js";
+import { removeMcp } from "./lib/claude-ops.js";
 import {
   color,
   log,
-  note,
+  readUserMcpConfig,
   resultLastLine,
-  text,
   writeConfig,
 } from "./utils.js";
 
-const CONTEXT7_COMMAND = "npx";
-const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
-
-export async function installContext7Config(plugin, language, config) {
+export async function installContext7Config(
+  plugin,
+  language,
+  config,
+  {
+    removeMcpImpl = removeMcp,
+    readUserMcpConfigImpl = readUserMcpConfig,
+    writeConfigImpl = writeConfig,
+    logImpl = log,
+  } = {}
+) {
   if (plugin.name !== "context7-plugin") return;
 
-  log.blank();
-  await note(
-    language === "zh"
-      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
-      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
-    language === "zh" ? "配置 Context7" : "Configure Context7"
-  );
-
-  const apiKey = await text({
-    message: language === "zh"
-      ? "输入你的 Context7 API key（或按 Enter 跳过）"
-      : "Enter your Context7 API key (or press Enter to skip)",
-    placeholder: "ctx7sk-...",
-    validate: (value) => {
-      if (!value) return;
-      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
-        return language === "zh"
-          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
-          : "API key should start with ctx7sk- or ctx7_";
-      }
-    },
-  });
-
-  if (apiKey) {
-    config.context7ApiKey = apiKey;
-    writeConfig(config);
+  let removedStoredApiKey = false;
+  if (config && Object.hasOwn(config, "context7ApiKey")) {
+    delete config.context7ApiKey;
+    writeConfigImpl(config);
+    removedStoredApiKey = true;
+    logImpl.info(
+      language === "zh"
+        ? "  已移除旧的 Context7 API key 本地配置，当前官方插件不再使用该安装方式"
+        : "  Removed legacy local Context7 API key config; the official plugin no longer uses that install path"
+    );
+  }
 
-    const r = await addMcp(buildContext7Mcp(apiKey));
+  const userMcps = readUserMcpConfigImpl();
+  if (!userMcps.has("context7")) {
+    return {
+      removedLegacyMcp: false,
+      removedStoredApiKey,
+    };
+  }
 
-    if (r.code === 0) {
-      log.ok(
-        language === "zh"
-          ? "  Context7 API key 已配置"
-          : "  Context7 API key configured"
-      );
-    } else if (r.stderr.includes("already exists")) {
-      await removeMcp({ name: "context7" });
-      const r2 = await addMcp(buildContext7Mcp(apiKey));
-      if (r2.code === 0) {
-        log.ok(
-          language === "zh"
-            ? "  Context7 API key 已更新"
-            : "  Context7 API key updated"
-        );
-      }
-    } else {
-      log.warn(
-        language === "zh"
-          ? `  Context7 MCP 配置失败: ${resultLastLine(r)}`
-          : `  Context7 MCP configuration failed: ${resultLastLine(r)}`
-      );
-      log.info(
-        color.dim(
-          language === "zh"
-            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-        )
-      );
-    }
-  } else {
-    log.info(
+  const result = await removeMcpImpl({ name: "context7" });
+  if (result.code === 0) {
+    logImpl.ok(
       language === "zh"
-        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
-        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
+        ? "  已移除遗留的用户级 context7 MCP，避免与官方 Context7 插件重复注册"
+        : "  Removed legacy user-level context7 MCP so the official Context7 plugin is the only owner"
     );
+    return {
+      removedLegacyMcp: true,
+      removedStoredApiKey,
+    };
   }
-}
 
-function buildContext7Mcp(apiKey) {
+  logImpl.warn(
+    language === "zh"
+      ? `  清理旧的 context7 MCP 失败: ${resultLastLine(result)}`
+      : `  Failed to remove legacy context7 MCP: ${resultLastLine(result)}`
+  );
+  logImpl.info(
+    color.dim(
+      language === "zh"
+        ? "     手动运行: claude mcp remove --scope user context7"
+        : "     Run manually: claude mcp remove --scope user context7"
+    )
+  );
   return {
-    name: "context7",
-    env: [`CONTEXT7_API_KEY=${apiKey}`],
-    command: CONTEXT7_COMMAND,
-    args: CONTEXT7_ARGS,
+    removedLegacyMcp: false,
+    removedStoredApiKey,
   };
 }

package/cli/install-required-plugins.js

@@ -1,6 +1,6 @@
 /**
  * Install required Claude Code companion plugins (today: context7-plugin).
- * Post-install, dispatches Context7 API-key configuration if applicable.
+ * Post-install, reconcile any legacy Context7 user-level MCP/config state.
  */
 
 import { addPluginMarketplace, installPlugin } from "./lib/claude-ops.js";
@@ -35,7 +35,7 @@ export async function installRequiredPlugins({
     if (ir.code === 0) {
       console.log(`  ${color.green("✓")} ${plugin.name} installed`);
 
-      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
+      if (plugin.name === "context7-plugin") {
         await installContext7Config(plugin, language, config);
       }
     } else {

package/cli/lib/config.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 const CONFIG_DIR = join(homedir(), ".claude");
-const CONFIG_FILE = join(CONFIG_DIR, "curdx-flow-config.json");
+export const CONFIG_FILE = join(CONFIG_DIR, "curdx-flow-config.json");
 
 export function readConfig() {
   if (!existsSync(CONFIG_FILE)) {

package/cli/lib/doctor-report.js

@@ -224,6 +224,7 @@ export function buildDoctorReport({
   projectTeamConfig,
   projectClaudeSettings,
   bundledPluginRuntimeDefaults,
+  legacyInstallState,
 }) {
   const lines = [];
   const sections = [];
@@ -402,6 +403,12 @@ export function buildDoctorReport({
           "migration: claude plugin update curdx-flow@curdx-flow-marketplace",
           "then restart Claude Code",
         ]
+        : duplicate.pluginEntry.plugin === "context7-plugin" && duplicate.name === "context7"
+          ? [
+            "official Context7 plugin already owns the context7 MCP server",
+            "run: npx @curdx/flow doctor --fix",
+            `or run manually: claude mcp remove --scope user ${duplicate.name}`,
+          ]
         : [
           `remove the duplicate user-level server if plugin:${duplicate.pluginEntry.plugin} should own it`,
           `run: claude mcp remove --scope user ${duplicate.name}`,
@@ -415,6 +422,20 @@ export function buildDoctorReport({
     }
   }
 
+  if (legacyInstallState?.hasLegacyContext7ApiKey) {
+    const legacySection = createSection("Legacy installer state:");
+    pushSectionLine(
+      legacySection,
+      "warn",
+      "legacy Context7 API key stored in curdx-flow install config",
+      [
+        `path: ${legacyInstallState.configPath}`,
+        "this key belonged to the retired user-level Context7 MCP install flow and is no longer used by the official context7-plugin",
+        "run: npx @curdx/flow doctor --fix",
+      ]
+    );
+  }
+
   if (claudeMemEnabled && runtimeStatus) {
     const runtimeSection = createSection("Runtime (claude-mem dependencies):");
     for (const [name, status] of Object.entries(runtimeStatus)) {

package/cli/uninstall-actions.js

@@ -124,7 +124,7 @@ export async function maybeRemoveBundledMcps(
   } = {}
 ) {
   logImpl.blank();
-  logImpl.info("Required MCP servers (context7, sequential-thinking)");
+  logImpl.info("Required user-level MCP servers (sequential-thinking)");
   if (shouldKeepBundledMcpsImpl({ yes, keepRecommended })) {
     logImpl.info(
       color.dim("--yes or --keep-recommended: keeping user-level MCPs (remove manually with `claude mcp remove <name>`)")

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

@@ -22,6 +22,7 @@ When a behavior is unclear, prefer the official docs and `claude plugin validate
 
 ## Hook Output Rules
 
+- Standard plugin hooks live at `hooks/hooks.json` in the plugin root and are discovered automatically. Do not also set `plugin.json.hooks` to that same file; current Claude runtimes treat that as a duplicate load.
 - `SessionStart` context injection must use:
   - `hookSpecificOutput.hookEventName = "SessionStart"`
   - `hookSpecificOutput.additionalContext = "..."`
@@ -74,9 +75,10 @@ Guarded artifact targets:
 - Claude Code plugin-root `settings.json` currently supports only `agent` and `subagentStatusLine`.
 - CurDX-Flow ships both:
   - `agent: "flow-orchestrator"` to route the main thread through the CurDX-Flow coordinator by default.
-  - `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
+- `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
 - The status-line script must fail open on malformed input or missing `python3`; UI decoration must never break agent execution.
 - Plugin-root references must never traverse outside the plugin directory. Installed marketplace plugins run from Claude Code's plugin cache, so parent-directory references are invalid even if they work in a development checkout.
+- CurDX-Flow should not declare `plugin.json.hooks` while using the standard `hooks/hooks.json` location; keep the file on disk, let Claude discover it implicitly, and reserve `plugin.json.hooks` for non-default or additional hook files only.
 - If adding plugin settings, update `schemas/plugin-settings.schema.json`, `test/plugin-structure-contract.test.js`, `test/pack-tarball-smoke.test.js`, and `scripts/validate-plugin-contracts.mjs` in the same change.
 
 ## Plugin Monitors and User Config
@@ -94,7 +96,7 @@ Guarded artifact targets:
 ## Plugin Dependency Constraints
 
 - Official dependency version constraints require upstream plugin release tags in the `{plugin-name}--v{version}` format.
-- Do not add a version constraint to the `context7-plugin` dependency unless the Upstash marketplace has matching `context7-plugin--v*` tags. A semver range without those tags can disable dependency resolution.
+- Do not add a version constraint to the `context7-plugin` dependency unless the Upstash marketplace has matching `context7-plugin--v*` tags. Claude resolves plugin dependency ranges against `{plugin-name}--v*` tags; a semver range without those tags can disable dependency resolution and surface the installed plugin version as `unknown`.
 - Keep the CLI registry and `.claude-plugin/plugin.json` dependency entry aligned: Context7 remains a required companion plugin, while optional tools stay in `RECOMMENDED_PLUGINS`.
 
 ## Shared Settings Guardrails

package/package.json

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