mustard-claude 3.0.15 → 3.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustard-claude",
-  "version": "3.0.15",
+  "version": "3.0.18",
   "description": "Framework-agnostic CLI for Claude Code project setup",
   "type": "module",
   "bin": {

package/templates/commands/mustard/bugfix/SKILL.md

@@ -19,9 +19,10 @@ Autonomous pipeline to diagnose and fix bugs. Zero context-switch — never ask
 ### Diff Context (automatic)
 Run `node .claude/scripts/diff-context.js` to capture the current git state. Include the output in the agent prompt as `{diff_context}` so agents know what has already changed.
 
-2. **DIAGNOSE:** Dispatch Explore agent:
+2. **DIAGNOSE:** Dispatch Explore agent (**≤20 tool uses, ≤3 full file reads**):
    - Scoped Grep searches with specific path + pattern for the error/symptom
-   - Trace callers/callees via Grep in relevant directories
+   - Trace callers/callees via Grep in relevant directories (prefer Grep over Read)
+   - Return as soon as root cause is clear — don't exhaustively scan
    - Return: root cause file(s), line(s), explanation
 3. **ASSESS — Decision point:**
    - Explore returns clear root cause in 1-2 files → **Fast Path** (skip PLAN)

package/templates/commands/mustard/feature/SKILL.md

@@ -56,6 +56,7 @@ Record scope for PLAN phase branching.
 
 **Path B — Explore agent ("medium")** (ONLY for genuinely new entities/patterns):
 - Entity NOT in registry AND new CRUD/entity → use Explore agent
+- **Explorer cap: ≤20 tool uses, ≤3 full file reads** — prefer Grep over Read
 - After Explore returns → go straight to PLAN, ZERO additional reads
 - NEVER duplicate reads the Explore agent already performed
 
@@ -140,12 +141,13 @@ When user chooses "Approve and implement now":
 
 After each agent returns, check the return value for an escalation status before advancing:
 
+- **Internal error** (no parseable output, empty return, API error) — re-dispatch **sequentially** (not parallel) with same prompt. Max 1 Internal retry per agent
 - `CONCERN` — record verbatim under `## Concerns` in the spec; continue to next step
 - `BLOCKED` — stop immediately; use `AskUserQuestion` to report the exact blocker; do NOT retry or advance
 - `PARTIAL` — apply Granular Retry Protocol from the last completed step; do NOT restart from step 1
 - `DEFERRED` — note in spec with agent justification; ask user if the deferred item is load-bearing before closing
 
-If two or more agents in the same wave return `CONCERN`, surface all concerns together before starting the next wave. See `pipeline-config.md` Escalation Statuses for the full status table.
+If two or more agents in the same wave return `CONCERN`, surface all concerns together before starting the next wave. See `pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
 
 9. **REVIEW** — dispatch review agent for each affected subproject (reads guards + relevant skills, runs 7-category checklist: SOLID, Design System, Patterns, i18n, Integration, Build, Elegance). REJECTED → fix + re-review (max 2 loops)
 10. All passed + APPROVED → CLOSE flow inline (sync registry, move spec, cleanup state)

package/templates/commands/mustard/resume/SKILL.md

@@ -111,12 +111,13 @@ Run `node .claude/scripts/diff-context.js` to capture the current git state. Inc
 
 After each agent returns, check the return value for an escalation status before advancing to the next wave:
 
+- **Internal error** (no parseable output, empty return, API error) — re-dispatch the failed agent(s) **sequentially** (not parallel) with the same prompt. Max 1 Internal retry per agent. If still failing: STOP + report
 - `CONCERN` — record verbatim under `## Concerns` in the spec; continue to next wave
 - `BLOCKED` — stop immediately; use `AskUserQuestion` to report the exact blocker; do NOT advance
 - `PARTIAL` — apply Granular Retry Protocol from the last completed step; do NOT restart from step 1
 - `DEFERRED` — note in spec with agent justification; ask user if the deferred item is load-bearing before closing
 
-If two or more agents in the same wave return `CONCERN`, surface all concerns together before dispatching the next wave. See `pipeline-config.md` Escalation Statuses for the full status table.
+If two or more agents in the same wave return `CONCERN`, surface all concerns together before dispatching the next wave. See `pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
 
 ### Step 4: Validate, Review & Complete
 

package/templates/commands/mustard/scan/SKILL.md

@@ -272,6 +272,8 @@ Body (below frontmatter):
 - **Read-only** — NEVER write, edit, or execute commands
 - Scope: `{subproject.path}/` directory only
 - Ignore: `bin/`, `obj/`, `node_modules/`, `.next/`, `Migrations/`
+- **Budget: ≤20 tool uses total, ≤3 full file reads** — prefer Grep over Read
+- Return findings as soon as pattern/root-cause is clear — do NOT exhaustively scan
 
 ## Return Format
 ### Findings

package/templates/hooks/rtk-rewrite.js

@@ -2,19 +2,23 @@
 /**
  * RTK REWRITE: PreToolUse hook that rewrites Bash commands through RTK
  *
- * If RTK (Rust Token Killer) is available in PATH, transparently prepends
- * `rtk ` to every Bash command, reducing token consumption by 60-90% on
- * CLI outputs.
+ * Uses `rtk rewrite` (the official hook API) to get the optimized command.
+ * Exit 0 + stdout = rewritten command; Exit 1 = no RTK equivalent.
+ *
+ * This approach:
+ * - Eliminates the "No hook installed" warning (no `rtk <cmd>` prefix)
+ * - Delegates command selection to RTK itself (no manual command set)
+ * - Works cross-platform (Windows + Unix)
  *
  * RTK availability is cached in a temp file (60s TTL) to avoid spawning
  * which/where on every command invocation.
  *
  * Fail-open: exits 0 on any error so Claude is never blocked by this hook.
  *
- * @version 1.0.0
+ * @version 2.0.0
  */
 
-const { execFileSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -23,43 +27,6 @@ const { shouldRun } = require('./_lib/hook-env.js');
 const CACHE_FILE = path.join(os.tmpdir(), 'rtk-available.json');
 const CACHE_TTL_MS = 60_000;
 
-/**
- * Commands RTK knows how to optimize. For anything else, pass through
- * unchanged to avoid unnecessary overhead.
- * Source: https://github.com/rtk-ai/rtk (supported commands)
- */
-const RTK_COMMANDS = new Set([
-  // Git
-  'git',
-  // Package managers
-  'npm', 'pnpm', 'yarn', 'bun', 'cargo', 'pip', 'pip3', 'bundle', 'gem',
-  'composer', 'go', 'poetry', 'nuget',
-  // Test runners
-  'pytest', 'vitest', 'jest', 'mocha', 'rspec', 'rake',
-  'playwright', 'cypress', 'nunit3-console', 'xunit.console',
-  // Build / lint
-  'eslint', 'biome', 'tsc', 'rustc', 'clippy', 'make', 'cmake', 'gradle',
-  'mvn', 'dotnet', 'msbuild', 'nuget',
-  // Bundlers / dev servers
-  'next', 'vite', 'webpack', 'turbo', 'nx', 'lerna', 'esbuild', 'rollup',
-  'parcel', 'rspack',
-  // CSS / preprocessors
-  'tailwindcss', 'sass', 'postcss', 'less',
-  // File / search
-  'ls', 'tree', 'find', 'grep', 'rg', 'cat', 'head', 'tail', 'wc',
-  'diff', 'sort', 'uniq',
-  // Network
-  'curl', 'wget',
-  // Containers
-  'docker', 'kubectl', 'podman', 'docker-compose',
-  // DB
-  'psql', 'mysql', 'sqlite3', 'mongosh',
-  // ORM / migration tools
-  'prisma', 'drizzle-kit', 'typeorm', 'sequelize',
-  // Misc
-  'env', 'printenv', 'gh',
-]);
-
 /**
  * Returns true if `rtk` is available in PATH, using a cached result when
  * the cache is still within TTL.
@@ -99,31 +66,24 @@ function isRtkAvailable() {
 }
 
 /**
- * Extracts the base command name from a shell command string.
- * Handles: env vars (FOO=bar cmd), paths (/usr/bin/cmd), sudo, npx/bunx wrappers.
+ * Asks RTK to rewrite the command. Returns the rewritten command string,
+ * or null if RTK has no optimized equivalent (exit code 1).
  */
-function extractBaseCommand(cmd) {
-  const trimmed = cmd.trim();
-  if (!trimmed) return null;
-
-  // Split on first pipe/semicolon/&& to get the first command
-  const firstCmd = trimmed.split(/[|;&]/)[0].trim();
-
-  // Tokenize respecting quotes
-  const tokens = firstCmd.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
-
-  for (const token of tokens) {
-    // Skip env variable assignments (FOO=bar)
-    if (/^[A-Za-z_]\w*=/.test(token)) continue;
-    // Skip sudo/env prefixes
-    if (token === 'sudo' || token === 'env') continue;
-    // Skip npx/bunx — let the actual command through
-    if (token === 'npx' || token === 'bunx') continue;
-    // Extract basename from paths (/usr/bin/git → git)
-    const base = path.basename(token);
-    return base;
+function rtkRewrite(cmd) {
+  try {
+    // rtk rewrite expects the raw command as args
+    // On Windows, shell: true is needed for proper quoting
+    const result = execSync(`rtk rewrite ${cmd}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'], // ignore stderr
+      timeout: 3000,
+    });
+    const rewritten = result.trim();
+    return rewritten || null;
+  } catch (_) {
+    // Exit 1 = no RTK equivalent, or timeout/error
+    return null;
   }
-  return null;
 }
 
 let input = '';
@@ -135,14 +95,15 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const cmd = data.tool_input?.command || '';
 
-    // Already prefixed or RTK not available — pass through
+    // Already prefixed with rtk or RTK not available — pass through
     if (cmd.startsWith('rtk ') || !isRtkAvailable()) {
       process.exit(0);
     }
 
-    // Extract the base command (first word, ignoring env vars and paths)
-    const baseCmd = extractBaseCommand(cmd);
-    if (!baseCmd || !RTK_COMMANDS.has(baseCmd)) {
+    // Ask RTK for the rewritten command
+    const rewritten = rtkRewrite(cmd);
+    if (!rewritten || rewritten === cmd) {
+      // No optimization available or same command — pass through
       process.exit(0);
     }
 
@@ -150,7 +111,7 @@ process.stdin.on('end', () => {
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
         permissionDecision: 'allow',
-        updatedInput: { command: 'rtk ' + cmd }
+        updatedInput: { command: `${rewritten} 2>/dev/null` }
       }
     }));
     process.exit(0);

package/templates/pipeline-config.md

@@ -66,6 +66,7 @@ When an agent fails during EXECUTE, classify the failure before deciding how to
 | **Transient** | Recoverable without new information — retry resolves it | Build cache stale, flaky test, race condition, timeout |
 | **Resolvable** | Fixable with a targeted patch — root cause is clear | Type mismatch, missing import, wrong argument, null guard |
 | **Structural** | Requires re-analysis — current approach is wrong | Wrong layer targeted, entity relation mismatch, spec assumption false |
+| **Internal** | Agent crashed or returned no parseable output | Context overflow, parallel dispatch race, internal API error, empty return |
 
 ### Routing Flow
 
@@ -73,6 +74,9 @@ When an agent fails during EXECUTE, classify the failure before deciding how to
 Agent fails
     │
     ▼
+Q0: Did the agent return parseable output?
+    NO  → Internal failure → re-dispatch SEQUENTIALLY (not parallel), same prompt (counts as retry 1)
+    YES ↓
 Q1: Is this a transient / environment issue? (cache, test flake, timeout)
     YES → Retry once immediately (no analysis needed)
     NO  ↓
@@ -84,13 +88,16 @@ Q3: Did the spec make a false assumption about structure or layer?
     NO  → Retry with expanded context (counts as retry 2) → if still failing: STOP + report
 ```
 
-### Classification Heuristic (3 Questions)
+### Classification Heuristic (4 Questions)
 
+0. **Internal?** — Did the agent crash with no parseable output (empty return, API error, context overflow)?
 1. **Transient?** — Would re-running the exact same command likely succeed?
 2. **Resolvable?** — Can you identify the fix without reading additional files?
 3. **Structural?** — Does the failure reveal the spec assumed something that isn't true?
 
-Answer all three before acting. Misclassifying Structural as Resolvable wastes a retry and deepens context.
+Answer Q0 first. If Internal: re-dispatch the failed agent(s) **sequentially** (one at a time, not parallel) with the same prompt. If multiple agents in a wave failed with Internal errors, this avoids the parallel dispatch race that likely caused the crash. Max 1 Internal retry per agent — if it fails again: STOP + report.
+
+Answer Q1-Q3 before acting on non-Internal failures. Misclassifying Structural as Resolvable wastes a retry and deepens context.
 
 ### Token Savings Rationale
 
@@ -140,11 +147,17 @@ Agents load context via skills (auto-triggered by Claude based on task descripti
 | Entity registry | `.claude/entity-registry.json` | Grep by entity name |
 
 ## Token Budget per Agent
-| Agent Type | Max Context | Includes |
-|------------|-------------|----------|
-| {subproject}-impl | ≤5K tokens | CLAUDE.md + auto-loaded skills + entity info + task steps |
-| explorer | ≤2.5K tokens | CLAUDE.md + search scope |
-| review | ≤3K tokens | CLAUDE.md + guards + file list |
+| Agent Type | Max Context | Max Tool Uses | Includes |
+|------------|-------------|---------------|----------|
+| {subproject}-impl | ≤5K tokens | — | CLAUDE.md + auto-loaded skills + entity info + task steps |
+| explorer | ≤2.5K tokens | **≤20** | CLAUDE.md + search scope |
+| review | ≤3K tokens | — | CLAUDE.md + guards + file list |
+
+**Explorer efficiency rules:**
+- Max 20 tool uses per explorer (Grep + Read + Glob combined)
+- Prefer Grep over Read — search for specific patterns, don't read entire files
+- Max 3 full file reads per explorer — use Grep for the rest
+- Return findings as soon as root cause/pattern is clear — don't exhaustively scan
 
 ## Skill Recommendations
 

package/templates/scripts/security-scan.js

@@ -28,6 +28,18 @@ const SECRET_PATTERNS = [
   { name: 'Generic Secret Assignment', re: /(?:secret|password|passwd|api_key|apikey|token|auth_token)\s*[:=]\s*["'][^"']{8,}["']/gi },
 ];
 
+// File name patterns that commonly trigger false positives on generic patterns
+// (seeds with hashed passwords, error code constants, test fixtures, etc.)
+const FP_FILE_PATTERNS = [
+  /[Ss]eeder/,          // DatabaseSeeder.cs, UserSeeder.cs
+  /[Ss]eed[s]?\./,      // Seeds.cs, seed.ts
+  /ErrorCode/i,         // ApiExceptionErrorCodes.cs, ErrorCodes.ts
+  /Exception.*Code/i,   // ExceptionCodes, ExceptionErrorCodes
+  /\.d\.ts$/,           // Type declaration files
+  /\.test\./,           // Test files
+  /\.spec\./,           // Spec files
+];
+
 // ── Ignore lists ────────────────────────────────────────────────────
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', 'dist', 'bin', 'obj', '.next', 'vendor',
@@ -73,11 +85,17 @@ function scanFile(filePath, results) {
   let content;
   try { content = fs.readFileSync(filePath, 'utf8'); } catch { return; }
 
+  // Check if file matches false-positive suppression patterns
+  const baseName = path.basename(filePath);
+  const isFpFile = FP_FILE_PATTERNS.some(re => re.test(baseName));
+
   // Secret pattern matching
   for (const { name, re } of SECRET_PATTERNS) {
     re.lastIndex = 0;
     const match = re.exec(content);
     if (match) {
+      // Skip generic patterns on known false-positive files
+      if (isFpFile && name === 'Generic Secret Assignment') continue;
       // Find line number
       const beforeMatch = content.substring(0, match.index);
       const line = (beforeMatch.match(/\n/g) || []).length + 1;

package/templates/scripts/sync-detect.js

@@ -597,8 +597,9 @@ function getGitDirtyFiles(subprojectPath) {
       if (!trimmed) continue;
       // Format: "XY filename" or "XY filename -> newname"
       const filePath = trimmed.substring(3).split(" -> ").pop().trim();
+      const fileName = path.basename(filePath);
       const ext = path.extname(filePath).toLowerCase();
-      if (!sourceExts.has(ext)) continue;
+      if (!sourceExts.has(ext) && !MANIFEST_FILES.has(fileName)) continue;
       // Skip ignored directories
       const parts = filePath.split("/");
       if (parts.some((p) => ignoreNames.has(p) || p === "migrations")) continue;
@@ -627,6 +628,26 @@ const SOURCE_IGNORE_PATTERNS = [
 
 const SOURCE_EXTENSIONS = new Set([".cs", ".ts", ".tsx", ".js", ".jsx", ".dart"]);
 
+/**
+ * Manifest files that affect project behavior without changing source code.
+ * Changes to these files (dependency upgrades, SDK bumps) should invalidate
+ * the source hash even when no source file changed.
+ */
+const MANIFEST_FILES = new Set([
+  // Flutter/Dart
+  "pubspec.yaml", "pubspec.lock",
+  // Node.js
+  "package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock",
+  // .NET
+  "Directory.Packages.props", "Directory.Build.props", "nuget.config",
+  // Go
+  "go.mod", "go.sum",
+  // Rust
+  "Cargo.toml", "Cargo.lock",
+  // Python
+  "pyproject.toml", "requirements.txt", "poetry.lock",
+]);
+
 /**
  * Recursively collect source files from a directory.
  * Respects ignore patterns and extension filters.
@@ -660,7 +681,7 @@ function collectSourceFiles(dir, maxDepth = 10, currentDepth = 0) {
         results.push(...collectSourceFiles(fullPath, maxDepth, currentDepth + 1));
       } else if (entry.isFile()) {
         const ext = path.extname(entry.name).toLowerCase();
-        if (SOURCE_EXTENSIONS.has(ext)) {
+        if (SOURCE_EXTENSIONS.has(ext) || MANIFEST_FILES.has(entry.name)) {
           results.push(relFromRoot);
         }
       }
@@ -909,6 +930,17 @@ function main() {
   }
   const subprojectPaths = submodulePaths;
 
+  // Load previous cache for hash comparison (anti-stale detection)
+  let previousCache = null;
+  try {
+    const cachePath = path.join(ROOT, ".claude", ".detect-cache.json");
+    if (fs.existsSync(cachePath)) {
+      previousCache = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+    }
+  } catch {
+    // no previous cache — treat all as changed
+  }
+
   // 2. Filter to only those with a CLAUDE.md, then build subproject entries
   const subprojects = [];
   const detectedAgentsSet = new Set();
@@ -944,6 +976,10 @@ function main() {
     // Detect git dirty state (uncommitted source file changes)
     const gitDirty = getGitDirtyFiles(normalizedPath);
 
+    // Compare current hash against previous cache to detect stale state
+    const prevHash = previousCache?.sourceHashes?.[name];
+    const hashChanged = !prevHash || prevHash !== sourceHashes[name];
+
     subprojects.push({
       name,
       path: normalizedPath,
@@ -951,6 +987,7 @@ function main() {
       agent,
       commands,
       stackSummary,
+      hashChanged,
       ...(gitDirty.dirty ? { gitDirty: true, gitDirtyCount: gitDirty.files.length } : {}),
     });
   }