moflo 4.9.12 → 4.9.14

package/dist/src/cli/init/moflo-yaml-template.js

@@ -0,0 +1,370 @@
+/**
+ * Canonical moflo.yaml renderer.
+ *
+ * Single source of truth shared by:
+ *   - `flo init` (src/cli/init/moflo-init.ts § Step 1)
+ *   - Session-start launcher self-heal (bin/session-start-launcher.mjs § 3d-yaml-create)
+ *
+ * The launcher path keeps consumers visible and tunable: when a project is
+ * upgraded to a moflo with new defaults but has no moflo.yaml at all, the
+ * sibling `bin/lib/yaml-upgrader.mjs` no-ops (it only appends to existing
+ * files). Without this module, the user has no surface to see/edit defaults
+ * after an `npm install moflo@*`. See issue #895.
+ *
+ * Companion: `bin/lib/yaml-upgrader.mjs` keeps EXISTING moflo.yaml files
+ * forward-compatible by appending new top-level sections. This module
+ * handles the MISSING case.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
+const WALK_SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.reports',
+    '.swarm', '.moflo', 'packages',
+]);
+const SOURCE_EXTENSIONS = [
+    '.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb', '.cs',
+];
+/**
+ * Top-level candidates for source directories. Same list `flo init` uses; the
+ * walker also descends to find `src/` and `migrations/` up to 3 levels deep.
+ */
+const SRC_TOP_LEVEL = ['packages', 'lib', 'app', 'apps', 'services', 'server', 'client'];
+const SRC_NAMES = new Set(['src', 'migrations']);
+export function discoverGuidanceDirs(root) {
+    const TOP_LEVEL = ['.claude/guidance', 'docs/guides', 'docs', 'architecture', 'adr', '.cursor/rules'];
+    const found = TOP_LEVEL.filter(d => fs.existsSync(path.join(root, d)));
+    function walk(dir, depth) {
+        if (depth > 3)
+            return;
+        try {
+            const entries = fs.readdirSync(path.join(root, dir), { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || WALK_SKIP_DIRS.has(entry.name))
+                    continue;
+                const rel = dir ? `${dir}/${entry.name}` : entry.name;
+                const guidancePath = `${rel}/.claude/guidance`;
+                if (fs.existsSync(path.join(root, guidancePath))) {
+                    try {
+                        const files = fs.readdirSync(path.join(root, guidancePath));
+                        if (files.some(f => f.endsWith('.md')))
+                            found.push(guidancePath);
+                    }
+                    catch { /* skip unreadable */ }
+                }
+                else {
+                    walk(rel, depth + 1);
+                }
+            }
+        }
+        catch { /* skip unreadable */ }
+    }
+    walk('', 0);
+    return found;
+}
+export function discoverTestDirs(root) {
+    const TOP_LEVEL = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+    const found = TOP_LEVEL.filter(d => fs.existsSync(path.join(root, d)));
+    function walk(dir, depth) {
+        if (depth > 3)
+            return;
+        try {
+            const entries = fs.readdirSync(path.join(root, dir), { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || WALK_SKIP_DIRS.has(entry.name))
+                    continue;
+                const rel = dir ? `${dir}/${entry.name}` : entry.name;
+                if (entry.name === '__tests__')
+                    found.push(rel);
+                else
+                    walk(rel, depth + 1);
+            }
+        }
+        catch { /* skip unreadable */ }
+    }
+    walk('', 0);
+    return found;
+}
+export function discoverSrcDirs(root) {
+    const found = [];
+    for (const d of SRC_TOP_LEVEL) {
+        if (fs.existsSync(path.join(root, d)))
+            found.push(d);
+    }
+    function walk(dir, depth) {
+        if (depth > 3)
+            return;
+        try {
+            const entries = fs.readdirSync(path.join(root, dir), { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || WALK_SKIP_DIRS.has(entry.name))
+                    continue;
+                const rel = dir ? `${dir}/${entry.name}` : entry.name;
+                if (SRC_NAMES.has(entry.name)) {
+                    try {
+                        const files = fs.readdirSync(path.join(root, rel));
+                        if (files.some(f => /\.(ts|tsx|js|jsx)$/.test(f)))
+                            found.push(rel);
+                    }
+                    catch { /* skip unreadable */ }
+                }
+                else {
+                    walk(rel, depth + 1);
+                }
+            }
+        }
+        catch { /* skip unreadable */ }
+    }
+    walk('', 0);
+    return found;
+}
+function scanExtensions(dir, extensions, depth, maxDepth) {
+    if (depth > maxDepth)
+        return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries.slice(0, 100)) {
+        if (entry.isDirectory() && !['node_modules', '.git', 'dist', 'build'].includes(entry.name)) {
+            scanExtensions(path.join(dir, entry.name), extensions, depth + 1, maxDepth);
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name);
+            if (SOURCE_EXTENSIONS.includes(ext))
+                extensions.add(ext);
+        }
+    }
+}
+export function detectExtensions(root, srcDirs) {
+    const extensions = new Set();
+    for (const dir of srcDirs) {
+        const fullDir = path.join(root, dir);
+        if (fs.existsSync(fullDir)) {
+            try {
+                scanExtensions(fullDir, extensions, 0, 3);
+            }
+            catch { /* skip */ }
+        }
+    }
+    return extensions.size > 0 ? [...extensions].sort() : ['.ts', '.tsx', '.js', '.jsx'];
+}
+export function defaultMofloYamlConfig(root) {
+    const guidanceDirs = discoverGuidanceDirs(root);
+    if (guidanceDirs.length === 0)
+        guidanceDirs.push('.claude/guidance');
+    const srcDirs = discoverSrcDirs(root);
+    if (srcDirs.length === 0)
+        srcDirs.push('src');
+    const testDirs = discoverTestDirs(root);
+    if (testDirs.length === 0)
+        testDirs.push('tests');
+    return {
+        projectName: path.basename(root),
+        guidanceDirs,
+        srcDirs,
+        testDirs,
+        detectedExts: detectExtensions(root, srcDirs),
+        guidance: true,
+        codeMap: true,
+        tests: true,
+        gates: true,
+        stopHook: true,
+    };
+}
+export function renderMofloYaml(config) {
+    const { projectName, guidanceDirs, srcDirs, testDirs, detectedExts, guidance, codeMap, tests, gates, stopHook } = config;
+    return `# MoFlo — Project Configuration
+# Generated by: moflo init
+# Docs: https://github.com/eric-cielo/moflo
+
+project:
+  name: "${projectName}"
+
+# Guidance/knowledge docs to index for semantic search
+guidance:
+  directories:
+${guidanceDirs.map(d => `    - ${d}`).join('\n')}
+  namespace: guidance
+
+# Source directories for code navigation map
+code_map:
+  directories:
+${srcDirs.map(d => `    - ${d}`).join('\n')}
+  extensions: [${detectedExts.map(e => `"${e}"`).join(', ')}]
+  exclude: [node_modules, dist, .next, coverage, build, __pycache__, target, .git]
+  namespace: code-map
+
+# Test file discovery and indexing
+tests:
+  directories:
+${testDirs.map(d => `    - ${d}`).join('\n')}
+  patterns: ["*.test.*", "*.spec.*", "*.test-*"]
+  extensions: [".ts", ".tsx", ".js", ".jsx"]
+  exclude: [node_modules, coverage, dist]
+  namespace: tests
+
+# Spell gates (enforced via Claude Code hooks)
+gates:
+  memory_first: ${gates}
+  task_create_first: ${gates}
+  context_tracking: ${gates}
+
+# Auto-index on session start
+auto_index:
+  guidance: ${guidance}
+  code_map: ${codeMap}
+  tests: ${tests}
+
+# Memory backend
+memory:
+  backend: sql.js
+  embedding_model: Xenova/all-MiniLM-L6-v2
+  namespace: default
+
+# Hook toggles (all on by default — disable to slim down)
+hooks:
+  pre_edit: true               # Track file edits for learning
+  post_edit: true              # Record edit outcomes, train neural patterns
+  pre_task: true               # Get agent routing before task spawn
+  post_task: true              # Record task results for learning
+  gate: ${gates}                   # Spell gate enforcement (memory-first, task-create-first)
+  route: true                  # Intelligent task routing on each prompt
+  stop_hook: ${stopHook}              # Session-end persistence and metric export
+  session_restore: true        # Restore session state on start
+  notification: true           # Hook into Claude Code notifications
+
+# MCP server options
+mcp:
+  tool_defer: deferred           # Defer 150+ tool schemas; loaded on demand via ToolSearch
+  auto_start: false              # Auto-start MCP server on session begin
+
+# Spell step sandboxing (OS-level process isolation for bash steps)
+# Platform support: macOS (sandbox-exec), Linux/WSL (bwrap). Windows has no OS sandbox.
+# Tiers:
+#   auto          — Use best available sandbox for this platform (recommended when enabled)
+#   denylist-only — Layer 1 only: block catastrophic commands, no OS isolation
+#   full          — Require full OS isolation; throws if the sandbox tool is unavailable
+sandbox:
+  enabled: false                 # Set to true to wrap bash steps in an OS sandbox
+  tier: auto                     # auto | denylist-only | full
+
+# Status line display (shown at bottom of Claude Code)
+# mode: "compact" (default), "single-line", or "dashboard" (full multi-line)
+status_line:
+  enabled: true
+  mode: compact
+  branding: "MoFlo V4"
+  show_git: true
+  show_session: true
+  show_swarm: true
+  show_mcp: true
+
+# Model preferences (haiku, sonnet, opus)
+# These are static fallbacks. When model_routing.enabled is true (default),
+# the dynamic router takes precedence based on task complexity.
+models:
+  default: opus        # Model for general tasks (kept high for unknowns)
+  research: sonnet     # Model for research/exploration agents
+  review: sonnet       # Code review never needs opus reasoning
+  test: sonnet         # Model for test-writing agents
+
+# Intelligent model routing (auto-selects haiku/sonnet/opus per task)
+# When enabled, overrides the static model preferences above
+# by analyzing task complexity and routing to the cheapest capable model.
+model_routing:
+  enabled: true                    # Set to false to pin to the static models above
+  confidence_threshold: 0.85       # Min confidence before escalating to a more capable model
+  cost_optimization: true          # Prefer cheaper models when confidence is high
+  circuit_breaker: true            # Penalize models that fail repeatedly
+  # Per-agent overrides (set to "inherit" to use routing, or a specific model to pin)
+  # agent_overrides:
+  #   security-architect: opus     # Always use opus for security
+  #   researcher: sonnet           # Pin research to sonnet
+`;
+}
+export function ensureMofloYamlExists(root) {
+    const configPath = path.join(root, 'moflo.yaml');
+    if (fs.existsSync(configPath)) {
+        return { created: false, path: configPath };
+    }
+    const config = defaultMofloYamlConfig(root);
+    // atomicWriteFileSync writes a tmp sidecar then renames — concurrent
+    // SessionStart launchers race to last-writer-wins. We layer a "never
+    // overwrite" invariant on top: re-check existence right before the
+    // rename so the loser of the race observes the winner's file and skips.
+    if (fs.existsSync(configPath)) {
+        return { created: false, path: configPath };
+    }
+    atomicWriteFileSync(configPath, renderMofloYaml(config));
+    return {
+        created: true,
+        path: configPath,
+        detail: `${config.srcDirs.join(', ')} | ${config.detectedExts.join(', ')}`,
+    };
+}
+/**
+ * Top-level sections every shipped moflo.yaml must define. Mirrors the keys
+ * `renderMofloYaml` emits — kept in sync via the test
+ * `init-moflo-yaml-template.test.ts § renderMofloYaml`.
+ */
+export const REQUIRED_TOP_LEVEL_SECTIONS = [
+    'project',
+    'guidance',
+    'code_map',
+    'tests',
+    'gates',
+    'auto_index',
+    'memory',
+    'hooks',
+    'mcp',
+    'sandbox',
+    'status_line',
+    'models',
+    'model_routing',
+];
+// Precompiled at module load — validateMofloYaml can run from doctor probes
+// or session-start hot paths, neither of which should rebuild N regexes per call.
+const SECTION_REGEXES = REQUIRED_TOP_LEVEL_SECTIONS.map((section) => [section, new RegExp(`^${section}\\s*:`, 'm')]);
+/**
+ * Lightweight compliance check for a moflo.yaml on disk. Avoids pulling a
+ * full YAML parser dependency — matches the regex-based approach already
+ * used by `doctor.ts § checkTestDirs` and `bin/lib/yaml-upgrader.mjs`.
+ * Never throws — the doctor probe and session-start self-heal both expect
+ * a verdict even when the file is corrupt.
+ */
+export function validateMofloYaml(yamlPath) {
+    const result = {
+        exists: false,
+        valid: false,
+        issues: [],
+        missingSections: [],
+    };
+    if (!fs.existsSync(yamlPath)) {
+        result.issues.push({ kind: 'parse-error', detail: 'moflo.yaml does not exist' });
+        return result;
+    }
+    result.exists = true;
+    let content;
+    try {
+        content = fs.readFileSync(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        result.issues.push({ kind: 'unreadable', detail: err.message ?? String(err) });
+        return result;
+    }
+    if (content.trim().length === 0) {
+        result.issues.push({ kind: 'empty', detail: 'file is empty' });
+        return result;
+    }
+    for (const [section, re] of SECTION_REGEXES) {
+        if (!re.test(content))
+            result.missingSections.push(section);
+    }
+    if (result.missingSections.length > 0) {
+        result.issues.push({
+            kind: 'missing-section',
+            detail: `missing top-level sections: ${result.missingSections.join(', ')}`,
+        });
+    }
+    result.valid = result.issues.length === 0;
+    return result;
+}
+//# sourceMappingURL=moflo-yaml-template.js.map

package/dist/src/cli/mcp-tools/hooks-tools.js

@@ -2739,6 +2739,8 @@ export const hooksModelRoute = {
     },
     handler: async (params) => {
         const task = params.task;
+        const preferCost = params.preferCost;
+        const preferSpeed = params.preferSpeed;
         const router = await getModelRouterInstance();
         if (!router) {
             // Fallback to simple heuristic
@@ -2751,7 +2753,7 @@ export const hooksModelRoute = {
                 implementation: 'fallback',
             };
         }
-        const result = await router.route(task);
+        const result = await router.route(task, { preferCost, preferSpeed });
         return {
             model: result.model,
             confidence: result.confidence,

package/dist/src/cli/movector/model-router.js

@@ -67,6 +67,11 @@ export const COMPLEXITY_INDICATORS = {
         'delete', 'documentation', 'readme', 'config', 'version', 'bump',
     ],
 };
+/**
+ * Score window (absolute score units) within which a model is considered
+ * "competitive" with the best — used by preferCost/preferSpeed tie-breaking.
+ */
+const COMPETITIVE_SCORE_WINDOW = 0.1;
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -101,18 +106,24 @@ export class ModelRouter {
         this.state = this.loadState();
     }
     /**
-     * Route a task to the optimal model
+     * Route a task to the optimal model.
+     *
+     * Accepts `RouteOptions` (preferCost / preferSpeed / embedding) — the legacy
+     * `number[]` second-arg form is still accepted and treated as `embedding`.
      */
-    async route(task, embedding) {
+    async route(task, optionsOrEmbedding) {
+        const options = Array.isArray(optionsOrEmbedding)
+            ? { embedding: optionsOrEmbedding }
+            : (optionsOrEmbedding ?? {});
         const startTime = performance.now();
         // Analyze task complexity
-        const complexity = this.analyzeComplexity(task, embedding);
+        const complexity = this.analyzeComplexity(task, options.embedding);
         // Compute base model scores
         const scores = this.computeModelScores(complexity);
         // Apply circuit breaker adjustments
         const adjustedScores = this.applyCircuitBreaker(scores);
         // Select best model
-        const { model, confidence, uncertainty } = this.selectModel(adjustedScores, complexity.score);
+        const { model, confidence, uncertainty } = this.selectModel(adjustedScores, complexity, options);
         const inferenceTimeUs = (performance.now() - startTime) * 1000;
         // Build result
         const result = {
@@ -199,10 +210,12 @@ export class ModelRouter {
      * Compute task scope from content analysis
      */
     computeTaskScope(task, words) {
-        // Multi-file indicators
+        // Multi-file / multi-system indicators
         const multiFilePatterns = [
             /multiple files?/i, /across.*modules?/i, /refactor.*codebase/i,
             /all.*files/i, /entire.*project/i, /system.*wide/i,
+            /across\s+\S+\s*(services?|systems?|modules?|packages?|microservices?)/i,
+            /\b\d+\s+(services?|systems?|modules?|packages?|microservices?)\b/i,
         ];
         const hasMultiFile = multiFilePatterns.some(p => p.test(task)) ? 0.4 : 0;
         // Code generation indicators
@@ -263,27 +276,60 @@ export class ModelRouter {
         return adjusted;
     }
     /**
-     * Select the best model from scores
+     * Select the best model from scores.
+     *
+     * Selection rules (in order):
+     *   1. If `preferCost`: among models within COMPETITIVE_SCORE_WINDOW of the
+     *      best score, return the cheapest by `costMultiplier`.
+     *   2. If `preferSpeed`: same window, return the fastest by `speedMultiplier`.
+     *   3. Otherwise: return the highest-scoring model. Escalate one tier ONLY
+     *      when there are 2+ high-complexity indicators (real architecture
+     *      signal) — single-keyword tasks like "review" or "audit X" do not
+     *      force a more expensive model.
+     *
+     * Note: prior versions force-escalated `sonnet → opus` whenever
+     * `uncertainty > maxUncertainty (0.15)`, which fired on essentially every
+     * code-review-shaped task and defeated the cost-saving point of the router.
      */
-    selectModel(scores, complexityScore) {
-        // Get sorted models by score
+    selectModel(scores, complexity, options = {}) {
         const sorted = Object.entries(scores)
             .filter(([m]) => m !== 'inherit')
             .sort((a, b) => b[1] - a[1]);
         const [bestModel, bestScore] = sorted[0];
-        const [secondModel, secondScore] = sorted[1] || ['sonnet', 0];
-        // Confidence is how much better the best is vs second
-        const confidence = bestScore > 0 ? Math.min(1, bestScore / (bestScore + secondScore + 0.01)) : 0.5;
-        // Uncertainty based on score spread and complexity
+        const secondScore = sorted[1]?.[1] ?? 0;
+        const confidence = bestScore > 0
+            ? Math.min(1, bestScore / (bestScore + secondScore + 0.01))
+            : 0.5;
         const scoreSpread = bestScore - secondScore;
         const uncertainty = Math.max(0, 1 - scoreSpread - confidence * 0.5);
-        // Escalate if uncertainty is too high
-        let model = bestModel;
-        if (uncertainty > this.config.maxUncertainty && bestModel !== 'opus') {
-            // Escalate to more capable model
-            model = bestModel === 'haiku' ? 'sonnet' : 'opus';
+        if (options.preferCost) {
+            const threshold = bestScore - COMPETITIVE_SCORE_WINDOW;
+            const competitive = sorted
+                .filter(([, s]) => s >= threshold)
+                .sort((a, b) => MODEL_CAPABILITIES[a[0]].costMultiplier -
+                MODEL_CAPABILITIES[b[0]].costMultiplier);
+            return { model: competitive[0][0], confidence, uncertainty };
+        }
+        if (options.preferSpeed) {
+            const threshold = bestScore - COMPETITIVE_SCORE_WINDOW;
+            const competitive = sorted
+                .filter(([, s]) => s >= threshold)
+                .sort((a, b) => MODEL_CAPABILITIES[b[0]].speedMultiplier -
+                MODEL_CAPABILITIES[a[0]].speedMultiplier);
+            return { model: competitive[0][0], confidence, uncertainty };
+        }
+        // Real-architecture escalation: multiple high-complexity indicators
+        // (e.g. "architect" + "system", "design" + "distributed") signal work
+        // that's worth a more capable model even if the score curve favours sonnet.
+        const hasArchitectureSignal = complexity.indicators.high.length >= 2;
+        if (hasArchitectureSignal && bestModel !== 'opus') {
+            return {
+                model: bestModel === 'haiku' ? 'sonnet' : 'opus',
+                confidence,
+                uncertainty,
+            };
         }
-        return { model, confidence, uncertainty };
+        return { model: bestModel, confidence, uncertainty };
     }
     /**
      * Build human-readable reasoning
@@ -460,9 +506,9 @@ export async function routeToModel(task) {
 /**
  * Route with full result
  */
-export async function routeToModelFull(task, embedding) {
+export async function routeToModelFull(task, embeddingOrOptions) {
     const router = getModelRouter();
-    return router.route(task, embedding);
+    return router.route(task, embeddingOrOptions);
 }
 /**
  * Analyze task complexity without routing

package/dist/src/cli/services/hook-block-hash.js

@@ -263,7 +263,7 @@ export function isHookBlockLocked(settings) {
  */
 export function applyAdditiveRegeneration(settings, report) {
     if (report.missing.length === 0)
-        return { settings, added: 0 };
+        return { settings, added: 0, removed: 0 };
     const ref = getCachedReference().tree;
     const hooks = (settings.hooks ?? {});
     let added = 0;
@@ -289,7 +289,28 @@ export function applyAdditiveRegeneration(settings, report) {
     }
     if (added > 0)
         settings.hooks = hooks;
-    return { settings, added };
+    return { settings, added, removed: 0 };
+}
+/**
+ * Wholesale regeneration: replace `settings.hooks` with the canonical reference
+ * block. Drops extras (stale entries from previous moflo versions, e.g. the
+ * `gate.cjs session-reset` SessionStart hook removed in #842) AND adds missing
+ * entries — the additive variant only does the latter.
+ *
+ * The caller MUST check `isHookBlockLocked(settings)` first; if locked, the
+ * user has opted out and this function should not be called. Non-hooks fields
+ * on `settings` (permissions, env, claudeFlow.*, etc.) are preserved.
+ *
+ * Mutates `settings` in place; caller is responsible for writing the file.
+ */
+export function applyWholesaleRegeneration(settings, report) {
+    if (!report.drifted)
+        return { settings, added: 0, removed: 0 };
+    // Clone the cached reference so a later mutation of settings.hooks (by the
+    // launcher's settings.json migrations, doctor --fix, etc.) cannot corrupt
+    // the cached tree shared across `computeHookBlockDrift` calls in this process.
+    settings.hooks = structuredClone(getCachedReference().tree);
+    return { settings, added: report.missing.length, removed: report.extra.length };
 }
 /**
  * Format a drift report for human-readable output (multi-line, no colour).

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.12';
+export const VERSION = '4.9.14';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.12",
+  "version": "4.9.14",
   "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.11",
+    "moflo": "^4.9.13",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/scripts/post-install-bootstrap.mjs

@@ -73,6 +73,7 @@ export const BIN_HELPER_FILES = [
   'gate-hook.mjs',
   'prompt-hook.mjs',
   'hook-handler.cjs',
+  'simplify-classify.cjs',
 ];
 
 export const SOURCE_HELPER_FILES = [