claude-devkit-cli 1.4.1 → 1.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-devkit-cli",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "CLI toolkit for spec-first development with Claude Code — hooks, commands, guards, and test runners",
   "bin": {
     "claude-devkit": "./bin/devkit.js",

package/src/commands/init.js

@@ -37,15 +37,20 @@ export async function initGlobal({ force = false, hooks = false } = {}) {
   const globalSkillsDir = getGlobalSkillsDir();
   await mkdir(globalSkillsDir, { recursive: true });
 
+  const existing = await readGlobalManifest() || {};
+  const globalFiles = existing.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Installing global skills ---');
 
   let copied = 0; let skipped = 0; let identical = 0;
   for (const relPath of COMPONENTS.skills) {
-    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   const parts = [`${copied} copied`];
@@ -55,32 +60,36 @@ export async function initGlobal({ force = false, hooks = false } = {}) {
   log.info('Skills available in all projects via ~/.claude/skills/');
 
   if (hooks) {
-    await initGlobalHooks({ force });
+    await initGlobalHooks({ force, _globalFiles: updatedFiles, _skipManifestWrite: true });
   }
 
-  // Write global manifest
-  const existing = await readGlobalManifest() || {};
   await writeGlobalManifest({
     ...existing,
     globalInstalled: true,
     globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    files: updatedFiles,
     updatedAt: new Date().toISOString(),
   });
 }
 
-export async function initGlobalHooks({ force = false } = {}) {
+export async function initGlobalHooks({ force = false, _globalFiles, _skipManifestWrite = false } = {}) {
   const globalHooksDir = getGlobalHooksDir();
   await mkdir(globalHooksDir, { recursive: true });
 
+  const existing = _skipManifestWrite ? null : (await readGlobalManifest() || {});
+  const globalFiles = _globalFiles || existing?.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Installing global hooks ---');
 
   let copied = 0; let skipped = 0; let identical = 0;
   for (const relPath of COMPONENTS.hooks) {
-    const result = await installHookGlobal(relPath, globalHooksDir, { force });
+    const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
     if (result === 'copied') copied++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   await mergeGlobalSettings(globalHooksDir);
@@ -90,6 +99,15 @@ export async function initGlobalHooks({ force = false } = {}) {
   if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
   log.pass(`Global hooks: ${parts.join(', ')}`);
   log.info('Hooks registered in ~/.claude/settings.json — active in all projects');
+
+  if (!_skipManifestWrite) {
+    await writeGlobalManifest({
+      ...existing,
+      globalHooksInstalled: true,
+      files: updatedFiles,
+      updatedAt: new Date().toISOString(),
+    });
+  }
 }
 
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/commands/upgrade.js

@@ -23,23 +23,26 @@ export async function upgradeGlobal({ force = false } = {}) {
   const globalSkillsDir = getGlobalSkillsDir();
   await mkdir(globalSkillsDir, { recursive: true });
 
+  const meta = await readGlobalManifest() || {};
+  const globalFiles = meta.files || {};
+  const updatedFiles = { ...globalFiles };
+
   log.blank();
   console.log('--- Upgrading global skills ---');
   let updated = 0; let skipped = 0; let identical = 0;
 
   for (const relPath of COMPONENTS.skills) {
-    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
     if (result === 'copied') updated++;
     else if (result === 'identical') identical++;
     else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
   }
 
   let skillParts = [`${updated} updated`, `${identical} unchanged`];
   if (skipped > 0) skillParts.push(`${skipped} customized (use --force to overwrite)`);
   log.pass(`Global skills: ${skillParts.join(', ')}`);
 
-  const meta = await readGlobalManifest() || {};
-
   // Upgrade hooks if previously installed globally
   if (meta.globalHooksInstalled) {
     const globalHooksDir = getGlobalHooksDir();
@@ -50,10 +53,11 @@ export async function upgradeGlobal({ force = false } = {}) {
     let hUpdated = 0; let hSkipped = 0; let hIdentical = 0;
 
     for (const relPath of COMPONENTS.hooks) {
-      const result = await installHookGlobal(relPath, globalHooksDir, { force });
+      const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
       if (result === 'copied') hUpdated++;
       else if (result === 'identical') hIdentical++;
       else hSkipped++;
+      if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
     }
 
     await mergeGlobalSettings(globalHooksDir);
@@ -63,7 +67,7 @@ export async function upgradeGlobal({ force = false } = {}) {
     log.pass(`Global hooks: ${hookParts.join(', ')}`);
   }
 
-  await writeGlobalManifest({ ...meta, globalInstalled: true, updatedAt: new Date().toISOString() });
+  await writeGlobalManifest({ ...meta, globalInstalled: true, files: updatedFiles, updatedAt: new Date().toISOString() });
 
   // Warn about per-project skills that shadow global
   const projects = meta.projects || [];

package/src/lib/installer.js

@@ -203,24 +203,31 @@ export function getGlobalHooksDir() {
  * Copy a hook to the global ~/.claude/hooks/ directory.
  * Strips the '.claude/hooks/' prefix so path-guard.sh lands at
  * ~/.claude/hooks/path-guard.sh.
- * @returns {string} 'copied' | 'skipped' | 'identical'
+ * @param {object} [opts.globalFiles] - files section from global manifest, used to detect true customization
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false } = {}) {
+export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false, globalFiles = {} } = {}) {
   const stripped = hookRelPath.replace(/^\.claude\/hooks\//, '');
   const src = join(getTemplateDir(), hookRelPath);
   const dst = join(globalHooksDir, stripped);
 
+  const { hashFile } = await import('./hasher.js');
+  const srcHash = await hashFile(src);
+
   if (existsSync(dst) && !force) {
     try {
-      const { hashFile } = await import('./hasher.js');
-      const srcHash = await hashFile(src);
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
         log.same(`~/.claude/hooks/${stripped} (identical)`);
-        return 'identical';
+        return { result: 'identical', kitHash: srcHash };
+      }
+      const savedKitHash = globalFiles[hookRelPath]?.kitHash;
+      if (savedKitHash && dstHash === savedKitHash) {
+        // fall through to copy
+      } else {
+        log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash };
       }
-      log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
-      return 'skipped';
     } catch { /* hash failed */ }
   }
 
@@ -228,7 +235,7 @@ export async function installHookGlobal(hookRelPath, globalHooksDir, { force = f
   await fsCopyFile(src, dst);
   await chmod(dst, 0o755);
   log.copy(`~/.claude/hooks/${stripped}`);
-  return 'copied';
+  return { result: 'copied', kitHash: srcHash };
 }
 
 /**
@@ -331,29 +338,38 @@ export async function removeGlobalHooksFromSettings() {
  * Copy a skill to the global ~/.claude/skills/ directory.
  * Strips the '.claude/skills/' prefix so mf-plan/SKILL.md lands at
  * ~/.claude/skills/mf-plan/SKILL.md.
- * @returns {string} 'copied' | 'skipped' | 'identical'
+ * @param {object} [opts.globalFiles] - files section from global manifest, used to detect true customization
+ * @returns {{ result: 'copied'|'skipped'|'identical', kitHash: string }}
  */
-export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false } = {}) {
+export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false, globalFiles = {} } = {}) {
   const stripped = skillRelPath.replace(/^\.claude\/skills\//, '');
   const src = join(getTemplateDir(), skillRelPath);
   const dst = join(globalSkillsDir, stripped);
 
+  const { hashFile } = await import('./hasher.js');
+  const srcHash = await hashFile(src);
+
   if (existsSync(dst) && !force) {
     try {
-      const { hashFile } = await import('./hasher.js');
-      const srcHash = await hashFile(src);
       const dstHash = await hashFile(dst);
       if (srcHash === dstHash) {
         log.same(`~/.claude/skills/${stripped} (identical)`);
-        return 'identical';
+        return { result: 'identical', kitHash: srcHash };
+      }
+      // If the installed file still matches the kitHash we saved at last install,
+      // the user hasn't touched it — the kit just changed. Safe to update.
+      const savedKitHash = globalFiles[skillRelPath]?.kitHash;
+      if (savedKitHash && dstHash === savedKitHash) {
+        // fall through to copy
+      } else {
+        log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
+        return { result: 'skipped', kitHash: srcHash };
       }
-      log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
-      return 'skipped';
     } catch { /* hash failed, treat as conflict */ }
   }
 
   await mkdir(dirname(dst), { recursive: true });
   await fsCopyFile(src, dst);
   log.copy(`~/.claude/skills/${stripped}`);
-  return 'copied';
+  return { result: 'copied', kitHash: srcHash };
 }

package/templates/.claude/skills/mf-build/SKILL.md

@@ -15,6 +15,9 @@ TDD delivery loop — write failing tests from spec AS, implement story by story
    If no changes → "No source changes found. Specify a file or feature."
 
 2. **Read the spec** at `docs/specs/<feature>/<feature>.md` — the `## Stories` section with acceptance scenarios is your roadmap. The `## Overview` and `## Constraints` sections tell you the INTENT behind the code.
+
+3. **Locate related code:** If `codebase-memory-mcp` is available, use `search_code` to find all files touching this feature, and `trace_call_path` to understand dependency chain before writing tests — faster and more accurate than manual grep. Fallback: Grep for the main function/type names in the changed files.
+
 4. **Read existing tests** for the changed files — find patterns, fixtures, naming conventions. Don't duplicate.
 
 ---
@@ -111,19 +114,32 @@ Files: [test files touched]
 Stories: [AS-001 ✓, AS-002 ✓, AS-005 new]
 ```
 
-If behavior changed: "Consider updating the spec in docs/specs/<feature>/<feature>.md."
+### Spec Update Signal
+
+After every build, check against these conditions. If ANY is true → **must** signal.
 
-### Spec Gap Detection
+**Signal when (MUST):**
 
-If a test fails due to an edge case, error path, or boundary condition that is NOT covered by any existing AS in the spec:
+| # | Condition |
+|---|-----------|
+| S1 | A new test covers behavior, edge case, or error path with no corresponding AS in the spec |
+| S2 | Code behavior no longer matches the Given/When/Then of an existing AS (spec is stale) |
+| S3 | Implementation adds a new constraint or guard not documented in any AS or Constraints section |
 
-1. State explicitly: **"This failure suggests a missing acceptance scenario."**
-2. Describe the gap: what behavior was tested, which story it belongs to, why no AS covers it.
-3. Prompt: **"Run `/mf-plan <spec-path> 'Add AS for <description>'` to add the missing scenario, then re-run `/mf-build`."**
+**Do not signal when:**
+- Pure refactor — behavior unchanged, all existing AS still map correctly
+- Performance fix — same output, just faster
+- Fix to match spec — code was wrong, spec was right, no new behavior added
+
+**Signal format:**
+```
+⚠️ Spec Update Needed — run `/mf-plan docs/specs/<feature>/<feature>.md '<describe change>'`
+Reason: [S1 | S2 | S3] — <one line: what is missing or mismatched>
+```
 
-Do not silently fix the test and move on. A test that has no corresponding AS means the spec is incomplete — the spec must be updated first.
+If S1 applies to a failing test: state **"This failure suggests a missing acceptance scenario."** Describe the gap and prompt to run `/mf-plan` before re-running `/mf-build`. Do not silently add the test without the AS.
 
 ## Rules
 1. **Behavior over implementation.** Test what code DOES, not how.
 2. **Independent tests.** Each test sets up its own state, cleans up after.
-3. **Spec stays upstream.** If a test reveals a spec gap, update the spec before adding the test.
+3. **Spec stays upstream.** If a test reveals a spec gap (S1), signal and update the spec before adding the test. If code drifts from spec (S2), signal. If new constraint added (S3), signal.

package/templates/.claude/skills/mf-fix/SKILL.md

@@ -13,7 +13,7 @@ Bug: $ARGUMENTS
 Don't jump to code. Understand the bug first:
 
 1. **Parse the report.** Symptom? Expected vs actual? Repro steps?
-2. **Locate the code.** Grep for keywords from the bug (error messages, function names).
+2. **Locate the code.** If `codebase-memory-mcp` is available, use `search_code("<error message or function name>")` to find related files faster, and `trace_call_path` to map callers and impact radius. Fallback: Grep for keywords from the bug (error messages, function names).
 3. **Check history.** `git log --oneline -5 -- <file>` and `git blame -L <range> <file>` — who changed this last and why?
 4. **Form a hypothesis:** "I believe the bug is caused by [X] in [file:function] because [evidence]."
 
@@ -102,7 +102,27 @@ Prevention: <suggestion>
 Full suite: All passing ✓
 ```
 
-If the bug reveals an undocumented edge case: "Consider updating the spec at docs/specs/<feature>/<feature>.md."
+### Spec Update Signal
+
+After fixing, check these conditions. If ANY is true → **must** signal.
+
+**Signal when (MUST):**
+
+| # | Condition |
+|---|-----------|
+| S1 | Fix covers an edge case or error path with no corresponding AS in the spec |
+| S2 | Bug existed because an AS described wrong behavior — After fix, code and AS now conflict |
+| S3 | Fix adds a new constraint or guard (null check, balance guard, validation) not in spec |
+
+**Do not signal when:**
+- Fix is a clear typo/off-by-one — code was always wrong relative to spec, no new behavior
+- Performance-only fix — output unchanged
+
+**Signal format:**
+```
+⚠️ Spec Update Needed — run `/mf-plan docs/specs/<feature>/<feature>.md '<describe change>'`
+Reason: [S1 | S2 | S3] — <one line: what is missing or mismatched>
+```
 
 ## Multiple Bugs
 

package/templates/.claude/skills/mf-review/SKILL.md

@@ -13,6 +13,7 @@ Pre-merge code review — security, correctness, spec alignment.
    ```
 2. Check for spec in `docs/specs/<feature>/<feature>.md` — review against INTENT.
 3. Read the diff: `git diff "$BASE"...HEAD`
+4. **Expand blast radius:** If `codebase-memory-mcp` is available, use `search_code("<changed function or type>")` to find files not in the diff that may be affected, and `get_architecture()` to check if changed files belong to a sensitive layer (auth, payment, core). Fallback: skip, review diff only.
 
 If `$ARGUMENTS` provided → scope to those files only.
 If diff > 500 lines → review file-by-file, prioritize by smart focus below.