mustard-claude 3.1.11 → 3.1.12

package/package.json

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

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

@@ -18,11 +18,14 @@
 | `review` | general-purpose | opus | Code quality review (SOLID, security, perf) |
 | `docs` | general-purpose | sonnet | Documentation generation |
 | `refactor` | Plan → general-purpose | sonnet/opus | Plan + approve + implement refactoring |
+| `implement` | general-purpose | sonnet | Single-dispatch implementation with inline guards/patterns/recipes (low-cost, standardized) |
 
 ## L0 Enforcement
 
 **CRITICAL**: Parent context does NOT read code, does NOT implement. ALL work happens in Task contexts.
 
+**Note on `implement`**: the orchestrator may run targeted Greps against `.md` context files (`guards.md`, `patterns.md`, `recipes.md`) to inject standardization slices into the dispatched prompt. Those files are configuration docs, not application code — reading them in the parent is allowed. Source code reads still happen only inside the dispatched Task.
+
 ## Flow
 
 ### analyze / review / docs
@@ -51,6 +54,14 @@
 4. **IMPLEMENT** — Task(general-purpose) to execute approved plan
 5. **VALIDATE** — Run build/tests
 
+### implement
+
+1. **GREP SLICES** — Orchestrator runs targeted Greps against `{subproject}/.claude/commands/guards.md`, `patterns.md`, `recipes.md` for the scope keyword. Use `output_mode: content`, `-C 2`, `head_limit: 20` (cap ~500 tokens per file). Greps return small slices, not full files.
+2. **DISPATCH** — Single `Task(general-purpose, sonnet)` with guards/patterns/recipe injected inline in the prompt, naming conventions explicit, and return format capped at 30 lines.
+3. **BUILD** — Agent runs build/type-check at the end and reports the result.
+4. **NO OVERHEAD** — No spec, no pipeline state, no review gate. Surgical.
+5. **ON CONCERN** — If the agent returns CONCERN, orchestrator shows it to the user and offers either `/feature` Light (more gates) or an adjusted `implement` prompt.
+
 ## Implementation
 
 ```javascript
@@ -139,6 +150,43 @@ Task({
   `
 })
 
+// implement — NEW ACTION
+// Orchestrator runs targeted Greps first (each ≤500 tokens output)
+const guards   = grep({path: `${sp}/.claude/commands/guards.md`,   pattern: keyword, output_mode: "content", "-C": 2, head_limit: 20});
+const patterns = grep({path: `${sp}/.claude/commands/patterns.md`, pattern: keyword, output_mode: "content", "-C": 2, head_limit: 20});
+const recipe   = grep({path: `${sp}/.claude/commands/recipes.md`,  pattern: keyword, output_mode: "content", "-C": 2, head_limit: 20});
+
+// Single dispatch with everything inlined
+Task({
+  subagent_type: "general-purpose",
+  model: "sonnet",
+  description: `Implement: ${scope}`,
+  prompt: `
+    # IMPLEMENTATION TASK (standardized, low-cost)
+    ## Scope: ${scope}
+
+    ## Guards (inline — do not re-read)
+    ${guards}
+
+    ## Patterns to follow
+    ${patterns}
+
+    ## Recipe
+    ${recipe}
+
+    ## Naming conventions
+    - PascalCase for classes/components
+    - camelCase for variables/functions
+    - snake_case for DB columns
+    - kebab-case for files/URLs
+
+    ## Return format
+    - ≤30 lines
+    - Sections: Files Changed (bullet list), Build result, Status (DONE/CONCERN/BLOCKED)
+    - Do NOT paste file contents
+  `
+})
+
 // compare — Phase 1: Parallel exploration
 subprojects.forEach(sp => Task({
   subagent_type: "Explore",
@@ -196,6 +244,14 @@ After receiving results from `audit` or `compare`:
 /task review "Contract entity"
 /task docs "API endpoints"
 /task refactor "extract PaymentService"
+/task implement "add logout button to header"
+/task implement "create GET /api/users endpoint"
 ```
 
 Replace `{subproject}` with actual subproject name. Single repo: omit the subproject argument.
+
+## When to use implement vs /feature vs refactor
+
+- `implement` — 1-3 arquivos, pattern conhecido, resultado verificável por build. Baixo custo, sem auditoria.
+- `/feature` Light — mudanças estruturadas com spec auditável e review gate. Custo médio.
+- `refactor` — reorganização sem mudança funcional (split, rename, extract). Tem fase de Plan separada.

package/templates/hooks/__tests__/hooks.test.js

@@ -628,3 +628,189 @@ describe("subagent-tracker.js overload detection", () => {
     }
   });
 });
+
+// ─── _lib/metrics-emit.js ───────────────────────────────────────────────────
+
+describe("_lib/metrics-emit.js", () => {
+  const { emitMetric } = require("../_lib/metrics-emit.js");
+
+  it("should append a valid JSONL line and create the metrics dir", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "metrics-emit-"));
+    try {
+      emitMetric("unit-test-event", {
+        tokensAffected: 123,
+        tokensSaved: 45,
+        note: "hello",
+        extras: { source: "test", count: 7 },
+        cwd: tmpDir,
+      });
+      const file = path.join(tmpDir, ".claude", ".metrics", "unit-test-event.jsonl");
+      assert.ok(fs.existsSync(file), "JSONL file should be created");
+      const lines = fs.readFileSync(file, "utf8").trim().split("\n");
+      assert.equal(lines.length, 1, "should have one line");
+      const entry = JSON.parse(lines[0]);
+      assert.equal(entry.event, "unit-test-event");
+      assert.equal(entry.tokens_affected, 123);
+      assert.equal(entry.tokens_saved, 45);
+      assert.equal(entry.note, "hello");
+      assert.equal(entry.source, "test");
+      assert.equal(entry.count, 7);
+      assert.ok(entry.ts, "ts must be set");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("should fail-silent when the cwd is unwritable / invalid", () => {
+    // Pointing cwd at an existing FILE (not dir) makes mkdir/append fail.
+    const tmpFile = path.join(os.tmpdir(), `metrics-emit-fail-${Date.now()}.tmp`);
+    fs.writeFileSync(tmpFile, "not-a-dir");
+    try {
+      // Must NOT throw
+      assert.doesNotThrow(() => {
+        emitMetric("should-not-throw", {
+          tokensAffected: 1,
+          tokensSaved: 1,
+          note: "x",
+          cwd: tmpFile, // a file, not a dir → mkdir under it will fail
+        });
+      });
+    } finally {
+      fs.rmSync(tmpFile, { force: true });
+    }
+  });
+
+  it("should default missing fields to safe values", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "metrics-emit-defaults-"));
+    try {
+      emitMetric("defaults-event", { cwd: tmpDir });
+      const file = path.join(tmpDir, ".claude", ".metrics", "defaults-event.jsonl");
+      const entry = JSON.parse(fs.readFileSync(file, "utf8").trim());
+      assert.equal(entry.tokens_affected, 0);
+      assert.equal(entry.tokens_saved, 0);
+      assert.equal(entry.note, "");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── context-budget.js metrics emission ─────────────────────────────────────
+
+describe("context-budget.js metrics emission", () => {
+  const hook = "context-budget.js";
+
+  it("should emit JSONL with tokens_saved > 0 and note='blocked' when over budget in strict mode", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx-budget-metrics-"));
+    try {
+      // Explore budget = 10_000 chars. Send a 12_000 char prompt → over budget.
+      const oversizePrompt = "x".repeat(12000);
+      const result = await runHook(hook, {
+        hook_event_name: "PreToolUse",
+        tool_name: "Task",
+        tool_input: {
+          subagent_type: "Explore",
+          description: "metrics test",
+          prompt: oversizePrompt,
+        },
+      }, { cwd: tmpDir, projectDir: tmpDir });
+
+      assert.equal(result.code, 0);
+      // strict mode is the default — denial expected
+      assert.equal(result.parsed?.permissionDecision, "deny");
+
+      const metricsFile = path.join(tmpDir, ".claude", ".metrics", "budget-check.jsonl");
+      assert.ok(fs.existsSync(metricsFile), "budget-check.jsonl must exist");
+      const lines = fs.readFileSync(metricsFile, "utf8").trim().split("\n");
+      const entry = JSON.parse(lines[lines.length - 1]);
+      assert.equal(entry.event, "budget-check");
+      assert.equal(entry.note, "blocked");
+      assert.ok(entry.tokens_saved > 0, "tokens_saved should be > 0 on block");
+      assert.ok(entry.tokens_affected > 0, "tokens_affected should reflect prompt size");
+      assert.equal(entry.would_block, true);
+      assert.equal(entry.role, "Explore");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("should emit note='passed' and tokens_saved=0 when under budget", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx-budget-metrics-pass-"));
+    try {
+      const result = await runHook(hook, {
+        hook_event_name: "PreToolUse",
+        tool_name: "Task",
+        tool_input: {
+          subagent_type: "Explore",
+          description: "small",
+          prompt: "x".repeat(500),
+        },
+      }, { cwd: tmpDir, projectDir: tmpDir });
+
+      assert.equal(result.code, 0);
+      const metricsFile = path.join(tmpDir, ".claude", ".metrics", "budget-check.jsonl");
+      assert.ok(fs.existsSync(metricsFile));
+      const entry = JSON.parse(fs.readFileSync(metricsFile, "utf8").trim().split("\n").pop());
+      assert.equal(entry.note, "passed");
+      assert.equal(entry.tokens_saved, 0);
+      assert.ok(entry.tokens_affected > 0);
+      assert.equal(entry.would_block, false);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── spec-hygiene.js metrics emission ───────────────────────────────────────
+
+describe("spec-hygiene.js metrics emission", () => {
+  const hook = "spec-hygiene.js";
+
+  it("should emit spec-hygiene-move with tokens_saved > 0 when an active spec is auto-moved", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "spec-hygiene-metrics-"));
+    try {
+      const specName = "2026-04-10-test-completed";
+      const specDir = path.join(tmpDir, ".claude", "spec", "active", specName);
+      fs.mkdirSync(specDir, { recursive: true });
+      // A spec marked completed with all checklist items done → auto-move.
+      const body = [
+        "# Test",
+        "",
+        "### Status: completed | Phase: CLOSE | Scope: light",
+        "",
+        "## Checklist",
+        "",
+        "- [x] step one",
+        "- [x] step two",
+        "",
+        // Pad the file so tokensSaved > 0 (file size / 4 must round up)
+        "## Body",
+        "lorem ipsum ".repeat(50),
+        "",
+      ].join("\n");
+      fs.writeFileSync(path.join(specDir, "spec.md"), body);
+
+      const result = await runHook(hook, {
+        hook_event_name: "SessionStart",
+      }, { cwd: tmpDir, projectDir: tmpDir });
+
+      assert.equal(result.code, 0);
+
+      // Spec must have moved
+      const completedSpec = path.join(tmpDir, ".claude", "spec", "completed", specName, "spec.md");
+      assert.ok(fs.existsSync(completedSpec), "spec must be relocated to completed/");
+
+      // Metric must be emitted
+      const metricsFile = path.join(tmpDir, ".claude", ".metrics", "spec-hygiene-move.jsonl");
+      assert.ok(fs.existsSync(metricsFile), "spec-hygiene-move.jsonl must exist");
+      const entry = JSON.parse(fs.readFileSync(metricsFile, "utf8").trim().split("\n").pop());
+      assert.equal(entry.event, "spec-hygiene-move");
+      assert.ok(entry.tokens_saved > 0, "tokens_saved must be > 0");
+      assert.ok(entry.tokens_affected > 0);
+      assert.ok(/stale spec/i.test(entry.note));
+      assert.ok(entry.from && entry.to, "extras (from/to) must be present");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/templates/hooks/_lib/metrics-emit.js

@@ -0,0 +1,50 @@
+'use strict';
+/**
+ * metrics-emit — shared helper for appending enforcement metrics to JSONL.
+ *
+ * Schema (one line per call):
+ *   { ts, event, tokens_affected, tokens_saved, note, ...extras }
+ *
+ * Files live under `.claude/.metrics/{event}.jsonl`. `metrics-report.js`
+ * iterates every `*.jsonl` in that dir, so per-event sharding is compatible.
+ *
+ * Fail-silent: ANY error (mkdir, append, JSON stringify) is swallowed so
+ * hooks calling this never observe a throw. Hooks remain fail-open.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Append a metric line.
+ *
+ * @param {string} event  e.g. "budget-check", "spec-hygiene-move", "rtk-rewrite"
+ * @param {object} opts
+ * @param {number} [opts.tokensAffected=0]  Conservative tokens touched by this event.
+ * @param {number} [opts.tokensSaved=0]     Tokens prevented from entering context.
+ * @param {string} [opts.note='']           Short human label (e.g. "blocked", "passed").
+ * @param {object} [opts.extras={}]         Extra fields merged into the JSONL line.
+ * @param {string} [opts.cwd]               Override project dir (defaults to process.cwd()).
+ */
+function emitMetric(event, opts = {}) {
+  try {
+    if (!event || typeof event !== 'string') return;
+    const cwd = opts.cwd || process.cwd();
+    const dir = path.join(cwd, '.claude', '.metrics');
+    const file = path.join(dir, `${event}.jsonl`);
+    const line = {
+      ts: new Date().toISOString(),
+      event,
+      tokens_affected: Number.isFinite(opts.tokensAffected) ? opts.tokensAffected : 0,
+      tokens_saved: Number.isFinite(opts.tokensSaved) ? opts.tokensSaved : 0,
+      note: typeof opts.note === 'string' ? opts.note : '',
+      ...(opts.extras && typeof opts.extras === 'object' ? opts.extras : {}),
+    };
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(line) + '\n');
+  } catch (_) {
+    // fail-silent — never throw out of a hook
+  }
+}
+
+module.exports = { emitMetric };

package/templates/hooks/context-budget.js

@@ -22,6 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const { shouldRun } = require('./_lib/hook-env.js');
+const { emitMetric } = require('./_lib/metrics-emit.js');
 
 function getMode() {
   if (process.env.CONTEXT_BUDGET_MODE) return process.env.CONTEXT_BUDGET_MODE;
@@ -33,8 +34,6 @@ function getMode() {
 }
 
 const MODE = getMode();
-const METRICS_DIR = path.join(process.cwd(), '.claude', '.metrics');
-const METRICS_FILE = path.join(METRICS_DIR, 'budget-observations.jsonl');
 
 // Conservative regex: only match .claude/skills/**/*.md, .claude/context/**/*.md, SKILL.md references
 const MD_REF_PATTERN = /\.claude\/(?:skills|context)\/[^\s"'`]+\.md|SKILL\.md/g;
@@ -94,18 +93,19 @@ process.stdin.on('end', () => {
           : subagentType;
 
         // ALWAYS log (unconditional, fail-silent) — all modes including strict
-        try {
-          fs.mkdirSync(METRICS_DIR, { recursive: true });
-          fs.appendFileSync(METRICS_FILE, JSON.stringify({
-            ts: new Date().toISOString(),
-            event: 'budget-check',
+        const wouldBlock = actual > limit;
+        emitMetric('budget-check', {
+          tokensAffected: Math.round(actual / 4),
+          tokensSaved: wouldBlock ? Math.max(0, Math.round((actual - limit) / 4)) : 0,
+          note: wouldBlock ? 'blocked' : 'passed',
+          extras: {
             role: roleLabel,
             actual_chars: actual,
             limit,
-            would_block: actual > limit,
-            mode: MODE
-          }) + '\n');
-        } catch (_) {}
+            would_block: wouldBlock,
+            mode: MODE,
+          },
+        });
 
         // Apply mode decision (separate concern):
         if (MODE === 'observe') {

package/templates/hooks/rtk-rewrite.js

@@ -24,6 +24,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { shouldRun } = require('./_lib/hook-env.js');
+const { emitMetric } = require('./_lib/metrics-emit.js');
 
 const CACHE_FILE = path.join(os.tmpdir(), 'rtk-available.json');
 const CACHE_TTL_MS = 60_000;
@@ -109,6 +110,16 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Record the rewrite invocation. tokens_saved is intentionally 0 — actual
+    // token savings are measured by `rtk gain`. This metric only tracks how
+    // often the rewrite path fired so it can be correlated with the gain total.
+    emitMetric('rtk-rewrite', {
+      tokensAffected: Math.round(cmd.length / 4),
+      tokensSaved: 0,
+      note: 'rewritten via rtk',
+      extras: { command_head: cmd.slice(0, 60) },
+    });
+
     console.log(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',

package/templates/hooks/spec-hygiene.js

@@ -9,6 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const { shouldRun } = require('./_lib/hook-env.js');
+const { emitMetric } = require('./_lib/metrics-emit.js');
 
 try {
   if (!shouldRun('spec-hygiene')) process.exit(0);
@@ -50,10 +51,26 @@ function runHygiene() {
         const dest = path.join(completedDir, name);
         fs.mkdirSync(completedDir, { recursive: true });
 
+        // Capture spec size BEFORE the rename so the path still resolves.
+        let fileSize = 0;
+        try { fileSize = fs.statSync(specFile).size; } catch (_) { /* best-effort */ }
+
         // Phase 1 (critical): atomic rename. If this fails, state is untouched.
         fs.renameSync(specDir, dest);
         process.stderr.write(`[hygiene] Moved ${name} → completed/\n`);
 
+        // Heuristic: tokens "saved" ≈ file_size / 4 (chars-to-tokens). The spec
+        // would otherwise have been re-read in future sessions; moving it to
+        // completed/ removes it from the active scan path.
+        const tokens = Math.round(fileSize / 4);
+        emitMetric('spec-hygiene-move', {
+          tokensAffected: tokens,
+          tokensSaved: tokens,
+          note: 'stale spec moved from active/',
+          extras: { from: specDir, to: dest },
+          cwd,
+        });
+
         // Phase 2 (best-effort): cleanup orphan state files.
         // Each wrapped independently so a failure in one doesn't skip the others.
         const statesDir = path.join(cwd, '.claude', '.pipeline-states');

package/templates/scripts/metrics-report.js

@@ -63,8 +63,20 @@ const header = '| Event | Count | Tokens Affected | Tokens Saved | Notes |';
 const sep    = '|-------|-------|-----------------|--------------|-------|';
 console.log(header);
 console.log(sep);
+let totalSaved = 0;
+let totalAffected = 0;
+let totalCount = 0;
 for (const evt of events.sort()) {
   const { count, tokensAffected, tokensSaved, notes } = agg[evt];
   const noteStr = [...notes].slice(0, 2).join('; ') || '-';
-  console.log(`| ${evt} | ${count} | ${tokensAffected || '-'} | ${tokensSaved || '-'} | ${noteStr} |`);
+  // When the event records "affected" but no "saved" (e.g. rtk-rewrite,
+  // budget-check passing), surface the affected count instead of `-`.
+  const affectedCell = tokensAffected > 0 ? tokensAffected : '-';
+  const savedCell = tokensSaved > 0 ? tokensSaved : '-';
+  console.log(`| ${evt} | ${count} | ${affectedCell} | ${savedCell} | ${noteStr} |`);
+  totalSaved += tokensSaved;
+  totalAffected += tokensAffected;
+  totalCount += count;
 }
+console.log(sep);
+console.log(`| **TOTAL** | ${totalCount} | ${totalAffected || '-'} | ${totalSaved || '-'} | - |`);