@curdx/flow 2.3.7 → 2.3.9

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.7"
+    "version": "2.3.9"
   },
   "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.7",
+      "version": "2.3.9",
       "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.7",
+  "version": "2.3.9",
   "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/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.3.8
+
+- taught `doctor` to detect dirty CurDX-Flow source checkouts, so plugin developers immediately see when Claude cannot possibly be running their latest local edits yet
+- surfaced bundled source repo metadata (`branch`, `shortSha`, `exactTag`, `dirty`) alongside bundled plugin body version in diagnostics and JSON output
+- documented the reinstall workflow for “same version, but local source changed” plugin-development scenarios
+
 ## 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

package/cli/README.md

@@ -46,6 +46,8 @@ External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plug
 
 `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.
 
+When the CLI is running from a git checkout, `doctor` also reports whether that source repo is dirty. This catches the common plugin-development trap where Claude is still running the previously installed cache while your local checkout has uninstalled edits.
+
 ### 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

@@ -169,6 +169,13 @@ export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROO
     exists: false,
     packageVersion: null,
     pluginVersion: null,
+    sourceRepo: {
+      isGitRepo: false,
+      branch: null,
+      shortSha: null,
+      exactTag: null,
+      dirty: false,
+    },
     defaultAgent: null,
     subagentStatusLineCommand: null,
     monitorCount: 0,
@@ -199,6 +206,31 @@ export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROO
     state.packageVersion = null;
   }
 
+  const gitRepoCheck = runSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: packageRoot });
+  if (gitRepoCheck.code === 0 && gitRepoCheck.stdout.trim() === "true") {
+    state.sourceRepo.isGitRepo = true;
+
+    const branch = runSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: packageRoot });
+    if (branch.code === 0) {
+      state.sourceRepo.branch = branch.stdout.trim() || null;
+    }
+
+    const shortSha = runSync("git", ["rev-parse", "--short", "HEAD"], { cwd: packageRoot });
+    if (shortSha.code === 0) {
+      state.sourceRepo.shortSha = shortSha.stdout.trim() || null;
+    }
+
+    const exactTag = runSync("git", ["describe", "--tags", "--exact-match", "HEAD"], { cwd: packageRoot });
+    if (exactTag.code === 0) {
+      state.sourceRepo.exactTag = exactTag.stdout.trim() || null;
+    }
+
+    const status = runSync("git", ["status", "--short"], { cwd: packageRoot });
+    if (status.code === 0) {
+      state.sourceRepo.dirty = status.stdout.trim().length > 0;
+    }
+  }
+
   try {
     monitors = JSON.parse(await fs.readFile(monitorsPath, "utf-8"));
   } catch {

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/doctor-report.js

@@ -265,6 +265,7 @@ export function buildDoctorReport({
   const curdx = plugins.find((plugin) => plugin.name === "curdx-flow");
   const bundledVersion =
     bundledPluginRuntimeDefaults?.pluginVersion || bundledPluginRuntimeDefaults?.packageVersion || null;
+  const bundledSourceRepo = bundledPluginRuntimeDefaults?.sourceRepo || {};
   if (curdx) {
     if (curdx.status === "enabled") {
       pushLine(lines, "ok", `curdx-flow            v${curdx.version} (enabled)`);
@@ -280,6 +281,18 @@ export function buildDoctorReport({
           ]
         );
       }
+      if (bundledSourceRepo.isGitRepo && bundledSourceRepo.dirty) {
+        pushLine(
+          lines,
+          "warn",
+          "curdx-flow source repo has uninstalled local changes",
+          [
+            "the current CLI/source checkout has git modifications that Claude's installed plugin cannot see until you reinstall it",
+            "re-run: npx @curdx/flow install --all",
+            "then fully restart Claude Code before validating plugin behavior",
+          ]
+        );
+      }
     } else {
       pushLine(
         lines,
@@ -464,6 +477,28 @@ export function buildDoctorReport({
       );
     }
 
+    if (bundledSourceRepo.isGitRepo) {
+      const sourceSummary = [
+        bundledSourceRepo.branch,
+        bundledSourceRepo.shortSha,
+      ].filter(Boolean).join(" @ ");
+      const sourceDetails = [];
+      if (bundledSourceRepo.exactTag) {
+        sourceDetails.push(`exact tag: ${bundledSourceRepo.exactTag}`);
+      }
+      sourceDetails.push(
+        bundledSourceRepo.dirty
+          ? "git worktree dirty: local source changes are not reflected in Claude until reinstall"
+          : "git worktree clean"
+      );
+      pushSectionLine(
+        bundledRuntimeSection,
+        bundledSourceRepo.dirty ? "warn" : "info",
+        `Bundled source repo    ${sourceSummary || "git checkout detected"}`,
+        sourceDetails
+      );
+    }
+
     if (bundledPluginRuntimeDefaults.defaultAgent) {
       pushSectionLine(
         bundledRuntimeSection,

package/cli/lib/process.js

@@ -29,8 +29,13 @@ export function run(cmd, args = [], opts = {}) {
 /**
  * Sync run — for quick checks (e.g. "which claude").
  */
-export function runSync(cmd, args = []) {
-  const res = spawnSync(cmd, args, { encoding: "utf-8", shell: false });
+export function runSync(cmd, args = [], opts = {}) {
+  const res = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    shell: false,
+    cwd: opts.cwd,
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
   return {
     code: res.status ?? -1,
     stdout: res.stdout ?? "",

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