moflo 4.9.14 → 4.9.15

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -307,3 +307,4 @@ See `moflo-memory-strategy.md` for memory-specific troubleshooting.
 - `.claude/guidance/shipped/moflo-session-start.md` — Complete session-start lifecycle (DB heal, sync, migrations, daemon)
 - `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/` and how surgical self-heal works
 - `.claude/guidance/shipped/moflo-cross-platform.md` — Windows/macOS/Linux portability rules for any code change
+- `.claude/guidance/shipped/moflo-verbose-command-filtering.md` — Filter long verbose commands at the source; never tee-then-grep

package/.claude/guidance/shipped/moflo-verbose-command-filtering.md

@@ -0,0 +1,45 @@
+# Verbose Command Filtering — Filter at Source, Never Tee-Then-Read
+
+**Purpose:** Pipe long verbose commands (smoke runs, full test suites, builds with `--verbose`) through a filter at execution time so only relevant lines reach the model context. Never tee output to disk and `tail`/`grep` it later — every follow-up read re-loads the full file into context (~5K tokens per round-trip).
+
+---
+
+## The Rule
+
+| Pattern | Verdict |
+|---------|---------|
+| `cmd 2>&1 \| grep -E "FAIL\|Summary"` (run_in_background) | ✅ Filter at source |
+| `cmd 2>&1 \| tee .tmp.log` then later `tail`/`grep` `.tmp.log` | ❌ Tee-then-read |
+
+Tee-then-read is the silent context killer. The Bash tool surfaces stdout into context, so each follow-up `grep`/`tail` of a tee'd file re-reads the file fresh on every call. Three follow-ups burn 15K+ tokens before any decision lands. Filtering at source emits the matching lines once.
+
+## When to Apply
+
+Smoke harness runs, full `vitest`/`jest` suites, builds with `--verbose`, anything passing `--trace`, any `node ... --verbose` invocation. If you genuinely need the full log for post-mortem, write it to disk but inspect it OUTSIDE the model loop (have the user open it, attach it to an issue) — do NOT pipe a tee'd file back through Bash.
+
+## Concrete Examples
+
+```bash
+# ✅ Smoke harness
+node harness/consumer-smoke/run.mjs 2>&1 | grep -E "FAIL|Summary|Zombie"
+# ❌ node harness/consumer-smoke/run.mjs 2>&1 | tee .tmp.log; tail .tmp.log
+
+# ✅ Vitest full suite
+npm test -- --reporter=verbose 2>&1 | grep -E "FAIL|✗|Error:"
+# ❌ npm test 2>&1 | tee .test.log; grep FAIL .test.log
+
+# ✅ Build with verbose
+npm run build -- --verbose 2>&1 | grep -E "error TS|Failed|Cannot find"
+# ❌ npm run build 2>&1 | tee .build.log; grep "error TS" .build.log
+```
+
+## Why It Matters
+
+Case study: issue #903 burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline

package/.claude/helpers/simplify-classify.cjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * /simplify diff classifier — issue #908.
+ *
+ * Decides which review tier the current diff warrants and returns a JSON
+ * dispatch decision. The /simplify skill MUST call this first so routing is
+ * deterministic and unit-testable instead of a prose decision Claude makes
+ * over and over per run.
+ *
+ * Rule (per user direction): default to single-agent Sonnet review. Only
+ * escalate to a 3-agent fan-out when diff signals genuinely warrant it.
+ * Opus is never selected — the existing skill already documents that.
+ *
+ * Outputs JSON:
+ *   {
+ *     "tier": "TRIVIAL" | "SMALL" | "NORMAL",
+ *     "model": "sonnet",
+ *     "agentCount": 0 | 1 | 3,
+ *     "reasoning": [string, ...],
+ *     "stats": { added, deleted, fileCount, declAdded, declRemoved, ... }
+ *   }
+ *
+ * Usage:
+ *   node bin/simplify-classify.cjs [--base main]
+ *   node bin/simplify-classify.cjs --diff <unified-diff-on-stdin>
+ *
+ * The --diff stdin form exists so unit tests can drive the classifier
+ * with synthetic diffs (no git repo required).
+ */
+'use strict';
+
+const { execSync } = require('child_process');
+
+// Paths where new logic warrants the 3-agent fan-out (issue #908).
+// Mechanical edits inside these paths are still SMALL; only adding/removing
+// declarations triggers escalation.
+const SECURITY_PATHS = [
+  /(?:^|[\\\/])aidefence[\\\/]/i,
+  /(?:^|[\\\/])swarm[\\\/]consensus[\\\/]/i,
+  /(?:^|[\\\/])hooks?[\\\/](?:handlers?|gate|wiring)/i,
+  /(?:^|[\\\/])services[\\\/]daemon-lock\.ts$/i,
+  /(?:^|[\\\/])bin[\\\/]gate\./i,
+  /(?:^|[\\\/])bin[\\\/]session-start-launcher\./i,
+  /(?:^|[\\\/])\.claude[\\\/]helpers[\\\/]gate/i,
+];
+
+function safeExec(cmd) {
+  try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }); }
+  catch { return ''; }
+}
+
+function readDiffFromGit(base) {
+  // Combined diff: committed-since-base + working-tree
+  const committed = safeExec(`git diff ${base}...HEAD`);
+  const working = safeExec('git diff HEAD');
+  return committed + (working ? '\n' + working : '');
+}
+
+/**
+ * Parse a unified-diff string into per-file stats and aggregate signals.
+ * No git/I/O — pure function over the diff text. Test-friendly.
+ */
+function parseDiff(diff) {
+  const lines = diff.split('\n');
+  const files = new Map(); // filename → { added, deleted, declAdded, declRemoved, isNew, isRenamed }
+  let current = null;
+
+  // Match function/class/export-const-arrow/method declarations being
+  // added or removed. Conservative — biased toward false negatives so we
+  // don't over-escalate.
+  const DECL_RE = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type)\s+\w/;
+  const ARROW_DECL_RE = /^(?:export\s+)?(?:const|let|var)\s+\w+\s*[:=].*=>\s*\{?$/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+
+    // File header: `diff --git a/path b/path`
+    let m = ln.match(/^diff --git (?:a\/)?(.+?) (?:b\/)?(.+)$/);
+    if (m) {
+      const filename = m[2];
+      current = { filename, added: 0, deleted: 0, declAdded: 0, declRemoved: 0, isNew: false, isRenamed: false };
+      files.set(filename, current);
+      continue;
+    }
+    if (!current) continue;
+
+    if (ln.startsWith('new file mode')) current.isNew = true;
+    if (ln.startsWith('rename from') || ln.startsWith('rename to') || ln.startsWith('similarity index')) current.isRenamed = true;
+
+    // Skip diff headers
+    if (ln.startsWith('+++') || ln.startsWith('---') || ln.startsWith('@@') || ln.startsWith('index ')) continue;
+
+    if (ln.startsWith('+') && !ln.startsWith('+++')) {
+      current.added++;
+      const body = ln.slice(1).trim();
+      if (DECL_RE.test(body) || ARROW_DECL_RE.test(body)) current.declAdded++;
+    } else if (ln.startsWith('-') && !ln.startsWith('---')) {
+      current.deleted++;
+      const body = ln.slice(1).trim();
+      if (DECL_RE.test(body) || ARROW_DECL_RE.test(body)) current.declRemoved++;
+    }
+  }
+
+  // Aggregate
+  let added = 0, deleted = 0, declAdded = 0, declRemoved = 0;
+  let newFiles = 0, renamedFiles = 0;
+  let securityHit = false;
+  for (const f of files.values()) {
+    added += f.added;
+    deleted += f.deleted;
+    declAdded += f.declAdded;
+    declRemoved += f.declRemoved;
+    if (f.isNew) newFiles++;
+    if (f.isRenamed) renamedFiles++;
+    if (SECURITY_PATHS.some(rx => rx.test(f.filename))) securityHit = true;
+  }
+
+  return {
+    added, deleted, declAdded, declRemoved,
+    netDecls: declAdded - declRemoved,
+    fileCount: files.size,
+    newFiles, renamedFiles,
+    securityHit,
+    files: [...files.keys()],
+  };
+}
+
+/**
+ * Pure decision function. Takes parsed stats, returns dispatch decision.
+ * No I/O. Easy to unit-test with synthetic stats.
+ */
+function decide(stats) {
+  const reasoning = [];
+  const totalChange = stats.added + stats.deleted;
+
+  if (totalChange === 0) {
+    return { tier: 'TRIVIAL', model: 'sonnet', agentCount: 0, reasoning: ['empty diff — nothing to review'], stats };
+  }
+
+  // TRIVIAL: tiny diff, no declarations changed
+  if (totalChange <= 10 && stats.fileCount <= 1 && stats.netDecls === 0 && stats.declAdded === 0 && stats.declRemoved === 0) {
+    reasoning.push(`≤10 LOC in 1 file with no declaration changes`);
+    return { tier: 'TRIVIAL', model: 'sonnet', agentCount: 0, reasoning, stats };
+  }
+
+  // Mechanical relocation detection — the #906 case.
+  // If declarations were both ADDED and REMOVED at roughly matching rates,
+  // it's a structural move, not net-new logic. Judge by declaration balance,
+  // not raw LOC balance — formatting/blank-line differences between source
+  // and destination files easily push raw LOC out of balance even when the
+  // semantic change is purely "moved 5 functions across 5 new files".
+  // Mechanical relocations are SMALL even when many files / many lines.
+  const declTouched = stats.declAdded + stats.declRemoved;
+  const isMostlyRelocation = stats.declAdded >= 2
+    && stats.declRemoved >= 2
+    && Math.abs(stats.netDecls) <= Math.max(2, Math.floor(declTouched * 0.30));
+
+  if (isMostlyRelocation) {
+    reasoning.push(
+      `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
+    );
+    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+  }
+
+  // Escalation triggers — any one trips NORMAL (3 agents).
+  // Always Sonnet — Opus is never the right model for /simplify per skill rule.
+  const triggers = [];
+  if (totalChange > 500) triggers.push(`>500 LOC changed (${totalChange})`);
+  if (stats.fileCount >= 5 && stats.netDecls >= 3) triggers.push(`${stats.fileCount} files with ${stats.netDecls} net new declarations`);
+  if (stats.securityHit && stats.netDecls > 0) triggers.push('security-sensitive path with new logic');
+  if (stats.newFiles >= 3 && stats.declAdded >= 5) triggers.push(`${stats.newFiles} new files with ${stats.declAdded} new declarations`);
+
+  if (triggers.length > 0) {
+    return { tier: 'NORMAL', model: 'sonnet', agentCount: 3, reasoning: triggers, stats };
+  }
+
+  // Default: SMALL — single sonnet agent
+  reasoning.push(`small/medium diff: ${totalChange} LOC across ${stats.fileCount} file(s), +${stats.declAdded}/-${stats.declRemoved} decls`);
+  return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+}
+
+function classifyDiff(diffText) {
+  return decide(parseDiff(diffText));
+}
+
+function classifyFromGit(base = 'main') {
+  return classifyDiff(readDiffFromGit(base));
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const baseIdx = args.indexOf('--base');
+  const base = baseIdx >= 0 ? args[baseIdx + 1] : 'main';
+  const stdinDiff = args.includes('--diff') || args.includes('--stdin');
+
+  let result;
+  if (stdinDiff) {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (d) => { buf += d; });
+    process.stdin.on('end', () => {
+      result = classifyDiff(buf);
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    });
+  } else {
+    result = classifyFromGit(base);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
+}
+
+module.exports = { parseDiff, decide, classifyDiff, classifyFromGit };

package/.claude/skills/eldar/SKILL.md

@@ -92,15 +92,18 @@ Count `.md` files under `.claude/guidance/` (recursive). Severity table:
 
 ### 1g. Guidance Structure (only if 1f found ≥1 file)
 
-Apply the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md`. For each `.md` file, check:
+Invoke `/guidance -a` via the `Skill` tool to run the structural audit. The /guidance skill enforces the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md` (Purpose lines, See Also, generic H2s, hedged language, 500-line cap, RAG chunking) and is the single source of truth for those checks — never re-implement them here.
 
-- Has `**Purpose:**` line right after H1
-- Has `## See Also` at end
-- Under 500 lines
-- H2 headings are specific (not "Overview", "Configuration", "Examples")
-- No hedged language in rule contexts (`should`, `might`, `consider`)
+Fold the result into the Eldar report under the "Guidance structure" row:
 
-Do **not** duplicate `/guidance -a`'s logic verbatim — just produce a one-line summary per file (`<file>: <N issues>`). The Eldar surface gaps; `/guidance -a` does the deep audit.
+| Outcome of `/guidance -a` | Eldar row severity |
+|---------------------------|--------------------|
+| 0 files with issues       | ok                 |
+| 1–2 files with issues     | info               |
+| 3+ files with issues      | warn               |
+| `/guidance` itself errors | warn — quote the error verbatim so the user can fix the offending file before re-running |
+
+When the user is in `--fix` mode and chooses guidance fixes from the triage menu (3b), the same /guidance skill is the handoff target — so the audit and the fix flow share one implementation.
 
 ### 1h. Memory Health
 
@@ -204,7 +207,9 @@ TOP 3 RECOMMENDATIONS
 2. Add Drizzle conventions guidance (info — high leverage)
    You use Drizzle ORM but have no DB-conventions doc. This is the
    single highest-leverage gap for getting Claude to write idiomatic
-   queries and migrations in your codebase.
+   queries and migrations in your codebase. /guidance -a (run inline
+   in step 1g) flagged 3 existing docs with structural issues; pick
+   one to fix alongside this new one.
    See: .claude/guidance/shipped/moflo-guidance-rules.md
 
 3. Run `flo healer --fix` (warn)

package/.claude/skills/guidance/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: guidance
 description: Add, edit, or audit guidance docs in this project's .claude/guidance/ directory following moflo's universal guidance rules. Default mode walks the user through one doc (creating or improving it); the -a flag audits every doc in the directory and offers per-file improvements.
-arguments: "[-a] [<topic-or-path>]"
+arguments: "[-a] <topic-or-path>"
 ---
 
 # /guidance — Author and audit project guidance

package/.claude/skills/spell-schedule/SKILL.md

@@ -5,7 +5,7 @@ description: |
   Use when the user wants to schedule, automate, or recurringly run one of THEIR spells locally —
   e.g. "schedule the oap spell every hour", "run my audit spell every weekday at 9am", "fire X once tomorrow morning".
   This is the LOCAL daemon path. For remote Anthropic-cloud agents, use /schedule instead.
-arguments: "[spell-name-or-alias]"
+arguments: "<spell-name-or-alias>"
 ---
 
 # /spell-schedule — Schedule a Local Spell

package/dist/src/cli/commands/doctor-checks-deep.js

@@ -432,6 +432,31 @@ const REQUIRED_GATE_CASES = [
 // session-start-launcher.mjs in consumer projects without transitive failures.
 import { REQUIRED_HOOK_WIRING } from '../services/hook-wiring.js';
 export { REQUIRED_HOOK_WIRING };
+/**
+ * Detect "expected pre-publish drift" — source `bin/gate.cjs` is ahead of the
+ * installed `node_modules/moflo/bin/gate.cjs`, but the deployed
+ * `.claude/helpers/gate.cjs` still matches the installed version. This is the
+ * steady state in the moflo dogfood repo while a PR has landed but no
+ * `npm install moflo@<new>` has rotated the package.
+ *
+ * Returns true only when both are true:
+ *   - helper content equals installed bin content (helper is correctly synced
+ *     to what's installed)
+ *   - installed bin content differs from source bin content (source is ahead)
+ *
+ * If `node_modules/moflo/bin/gate.cjs` is missing (consumer never installed
+ * moflo, or path is unusual) we conservatively return false so other drift
+ * detection still applies.
+ */
+export function isExpectedPrePublishDrift(installedBinGate, helperContent, sourceBinContent) {
+    try {
+        const installedContent = readFileSync(installedBinGate, 'utf8');
+        return installedContent === helperContent && installedContent !== sourceBinContent;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Verify gate infrastructure health:
  * 1. gate.cjs exists and contains all required cases
@@ -474,14 +499,27 @@ export async function checkGateHealth() {
         issues.push(`gate.cjs missing cases: ${missingCases.join(', ')}`);
     }
     // 2. Check bin/gate.cjs sync
+    //
+    // The launcher syncs `node_modules/moflo/bin/gate.cjs` → `.claude/helpers/gate.cjs`
+    // on version change. Source `bin/gate.cjs` is only present in the moflo dogfood
+    // repo. During the dogfood publish window — between a PR landing and the next
+    // `npm install moflo@<new>` — source bin/ legitimately moves ahead of the
+    // installed bin/, while the helper continues to mirror the installed version.
+    // That's the expected steady state, not a bug; downgrade it to `warn` and skip
+    // the `fix` field so `--fix` doesn't paint a false success (#913).
     const binGate = join(projectDir, 'bin', 'gate.cjs');
+    const installedBinGate = join(projectDir, 'node_modules', 'moflo', 'bin', 'gate.cjs');
     if (existsSync(binGate)) {
         try {
             const binContent = readFileSync(binGate, 'utf8');
             if (binContent !== gateContent) {
-                // Check if it's a size difference (likely out of sync) vs whitespace
                 const sizeDiff = Math.abs(binContent.length - gateContent.length);
-                if (sizeDiff > 10) {
+                const prePublishDrift = isExpectedPrePublishDrift(installedBinGate, gateContent, binContent);
+                if (prePublishDrift) {
+                    warnings.push(`source bin/gate.cjs is ${sizeDiff} chars ahead of node_modules/moflo/bin/gate.cjs ` +
+                        '(expected pre-publish drift; resolves on next `npm install moflo@<new>`)');
+                }
+                else if (sizeDiff > 10) {
                     issues.push(`bin/gate.cjs out of sync with .claude/helpers/gate.cjs (${sizeDiff} chars differ)`);
                 }
                 else {

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.14';
+export const VERSION = '4.9.15';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.14",
+  "version": "4.9.15",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -81,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.13",
+    "moflo": "^4.9.14",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"