moflo 4.10.15 → 4.10.17

package/README.md

@@ -23,6 +23,19 @@ Or — just ask Claude to install MoFlo into your project and initialize it!
 
 To verify everything is running, ask Claude to run `flo healer` with full diagnostics after restarting. If anything fails, ask Claude to fix it with `flo healer --fix`. (`flo doctor` is still accepted as an alias.)
 
+## Next Step: Consult the Eldar
+
+After installing moflo, the single highest-leverage thing you can do for the best experience is run **`/eldar`** inside a Claude Code session.
+
+Where `flo healer` verifies that *moflo itself* is wired up correctly, **`/eldar` audits how Claude is set up to actually use your project** — guidance docs, CLAUDE.md, memory namespaces, hook/MCP wiring, model routing, and whether every technology in your stack (TypeScript, Python, Rust, Go, etc.) has matching guidance for Claude to lean on. The stack → guidance cross-reference alone is often the difference between *"Claude feels lost in this codebase"* and *"Claude knows this codebase"*.
+
+```
+/eldar          # Read-only audit; categorized findings, severity-ranked
+/eldar --fix    # Interactive triage — pick what to fix and the Eldar walk you through it
+```
+
+Run it on day one in any new project, any time Claude feels off, or as a periodic health check. Outside of the core install, this is the most impactful thing moflo offers — full details in the **`/eldar`** section [further down](#eldar--consult-the-eldar-project-setup-audit--wizard).
+
 ## Opinionated Defaults
 
 MoFlo makes deliberate choices so you don't have to:

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

@@ -262,14 +262,26 @@ export function computeHookBlockDrift(consumerHooks, referenceHooks) {
 // Settings.json helpers — shared between launcher + doctor
 // ────────────────────────────────────────────────────────────────────────────
 /**
- * True when the user has set `claudeFlow.hooks.locked: true` in their
- * settings.json — a sentinel that suppresses drift surfacing entirely.
+ * True when the user has set `moflo.hooks.locked: true` (canonical) or
+ * `claudeFlow.hooks.locked: true` (legacy alias) in their settings.json —
+ * a sentinel that suppresses drift surfacing entirely.
+ *
+ * The `claudeFlow.*` settings tree is a pre-rebrand legacy name that survives
+ * in writers + readers across the codebase. Renaming the whole tree is a
+ * separate effort; this one reader accepts `moflo.hooks.locked` ahead of the
+ * legacy key so the #1180 escape hatch is documented under the canonical
+ * brand from day one and consumers never have to migrate the key after we
+ * tell them to set it.
  */
 export function isHookBlockLocked(settings) {
     const root = settings;
+    const moflo = root?.moflo;
+    const mofloHooks = moflo?.hooks;
+    if (mofloHooks?.locked === true)
+        return true;
     const cf = root?.claudeFlow;
-    const hooks = cf?.hooks;
-    return hooks?.locked === true;
+    const cfHooks = cf?.hooks;
+    return cfHooks?.locked === true;
 }
 /**
  * Additively repair drift: for every entry in `report.missing`, locate the
@@ -309,26 +321,135 @@ export function applyAdditiveRegeneration(settings, report) {
         settings.hooks = hooks;
     return { settings, added, removed: 0 };
 }
+/**
+ * Set of helper-script basenames that moflo ships under `.claude/helpers/` and
+ * `.claude/scripts/`. Built once from `getReferenceHookBlock()` so it always
+ * tracks whatever the current reference block actually emits. Used by the
+ * wholesale-regen path to tell "stale moflo entry from a removed reference
+ * shape" (drop) apart from "consumer customisation we never owned" (preserve).
+ */
+let MOFLO_HELPER_BASENAMES_CACHE = null;
+function getMofloHelperBasenames() {
+    if (MOFLO_HELPER_BASENAMES_CACHE)
+        return MOFLO_HELPER_BASENAMES_CACHE;
+    const out = new Set();
+    const tree = getReferenceHookBlock();
+    for (const event of Object.keys(tree)) {
+        for (const block of tree[event]) {
+            for (const hook of block.hooks) {
+                const m = hook.command.match(/\.claude\/(?:helpers|scripts)\/([\w.\-]+)/);
+                if (m)
+                    out.add(m[1]);
+            }
+        }
+    }
+    MOFLO_HELPER_BASENAMES_CACHE = out;
+    return out;
+}
+/**
+ * True when a hook command references a moflo-shipped helper basename.
+ *
+ * Design: moflo "owns" the slot for any command pointing at one of its shipped
+ * helpers, so wholesale regen is free to replace that slot with the current
+ * reference. Conversely, a command pointing at a non-moflo helper basename is
+ * a consumer-owned customisation that must survive (#1180).
+ *
+ * Trade-off — hand-edits to a moflo helper command (e.g. consumer adds
+ * `--my-flag` to `gate-hook.mjs check-dangerous-command`) are treated as
+ * moflo-owned and replaced with the current reference shape on regen. The
+ * alternative (preserve any non-exact match) would silently retain stale
+ * entries like `gate.cjs session-reset` (removed in #842), defeating the
+ * whole point of wholesale regen. Consumers who need a tweaked moflo command
+ * should either lock the hook block via `moflo.hooks.locked: true`
+ * (`claudeFlow.hooks.locked` is still honoured as a legacy alias) or route
+ * through their own helper basename.
+ *
+ * Cross-platform: regex matches forward slashes only — what moflo always
+ * emits (Claude Code expands `$CLAUDE_PROJECT_DIR` on every OS). A consumer
+ * who hand-edited `settings.json` with backslashes on Windows would fail to
+ * match here and be treated as a customisation (preserved). That's the safer
+ * default — we'd rather keep an unfamiliar entry than delete user work.
+ */
+function isMofloOwnedHookEntry(command) {
+    const m = command.match(/\.claude\/(?:helpers|scripts)\/([\w.\-]+)/);
+    return m ? getMofloHelperBasenames().has(m[1]) : false;
+}
 /**
  * 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.
+ * block, then graft consumer customisations back in. Drops stale moflo entries
+ * (e.g. the `gate.cjs session-reset` SessionStart hook removed in #842) AND
+ * adds missing entries — the additive variant only does the latter.
+ *
+ * #1180 — `report.extra` carries both stale moflo entries AND consumer-owned
+ * customisations (e.g. waxstak's `project-analysis-gate.cjs`). The wholesale
+ * path used to drop both; it now distinguishes them via the helper-basename
+ * discriminator: any extra command referencing a moflo-shipped helper under
+ * `.claude/helpers/` or `.claude/scripts/` is stale moflo and gets dropped;
+ * anything else is consumer-owned and gets grafted back into the fresh tree
+ * under the same `(event, matcher)`, with its original `HookEntry`
+ * (type/timeout) snapshotted before the replace.
  *
  * 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.
+ * on `settings` (permissions, env, moflo.*, 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 };
+    // Snapshot full `HookEntry` objects for consumer customisations BEFORE we
+    // overwrite settings.hooks — the drift report carries command strings only,
+    // not timeout/type. Walk the consumer's existing tree, match against each
+    // non-moflo `extra` on (event, matcher, command).
+    const customisations = [];
+    const consumerHooks = (settings.hooks ?? {});
+    for (const extra of report.extra) {
+        if (isMofloOwnedHookEntry(extra.command))
+            continue;
+        const evtArr = consumerHooks[extra.event];
+        if (!Array.isArray(evtArr))
+            continue;
+        for (const block of evtArr) {
+            if ((block?.matcher ?? '') !== extra.matcher)
+                continue;
+            const found = Array.isArray(block.hooks)
+                ? block.hooks.find((h) => h?.command === extra.command)
+                : undefined;
+            if (found) {
+                customisations.push({ event: extra.event, matcher: extra.matcher, hook: found });
+                break;
+            }
+        }
+    }
     // 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 };
+    const fresh = structuredClone(getCachedReference().tree);
+    // Graft customisations into the fresh tree, slotting them under the same
+    // matcher block (created if absent).
+    for (const { event, matcher, hook } of customisations) {
+        let arr = fresh[event];
+        if (!Array.isArray(arr)) {
+            arr = [];
+            fresh[event] = arr;
+        }
+        let block = arr.find(b => (b?.matcher ?? '') === matcher);
+        if (!block) {
+            block = { hooks: [] };
+            if (matcher)
+                block.matcher = matcher;
+            arr.push(block);
+        }
+        if (!Array.isArray(block.hooks))
+            block.hooks = [];
+        if (!block.hooks.some((h) => h?.command === hook.command)) {
+            block.hooks.push(hook);
+        }
+    }
+    settings.hooks = fresh;
+    const removed = report.extra.length - customisations.length;
+    return { settings, added: report.missing.length, removed };
 }
 /**
  * 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.10.15';
+export const VERSION = '4.10.17';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.15",
+  "version": "4.10.17",
   "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",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.10.14",
+    "moflo": "^4.10.16",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"