moflo 4.10.14 → 4.10.16

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

@@ -145,6 +145,10 @@ For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox confi
 | Every 5+ file changes | `map` | Update codebase map |
 | Complex debugging | `deepdive` | Deep code analysis |
 
+### Worker Report Location
+
+Headless workers (`optimize`, `testgaps`, `ultralearn`, `refactor`, `deepdive`) write the latest run's full output to `.moflo/reports/<workerType>.<ext>` (`.md` for markdown workers, `.json` for `ultralearn`). The path is overwritten each run; for history, see `.moflo/logs/headless/`. The directory is gitignored by `flo init`, so reports never reach a consumer's commit. When the user asks "what did testgaps find?" or "where's the optimize report?", read `.moflo/reports/<workerType>.md` directly — do NOT re-run the worker.
+
 ### Memory-Enhanced Development
 
 | Action | When |

package/README.md

@@ -419,7 +419,7 @@ flo daemon status    # shows whether the service is registered AND running
 
 `flo spell schedule create` warns when the daemon isn't installed so you don't quietly miss runs.
 
-**Monitoring.** **[The Luminarium](#the-luminarium)** — moflo's localhost daemon dashboard — surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now), alongside worker health, memory stats, and Claude Code session stats. Each project gets its own deterministic port (33000–33999) recorded in `.moflo/daemon.lock`; ask `/luminarium` in your Claude session and it'll print the link.
+**Monitoring.** **[The Luminarium](#the-luminarium)** — moflo's localhost daemon dashboard — surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now), alongside worker health, memory stats, and Claude Code session stats. Ask `/luminarium` in your Claude session and it'll print the link.
 
 For full configuration (`scheduler:` block in `moflo.yaml`), event types, and the catch-up window after restarts, see [docs/SPELLS.md#scheduling](docs/SPELLS.md#scheduling).
 
@@ -465,13 +465,7 @@ The Luminarium is moflo's localhost daemon dashboard. It boots automatically wit
 
 ### Finding the URL
 
-Each project gets a deterministic port in the range 33000–33999, derived from a hash of the project root so two projects never collide on the same machine. The actual bound port is written to `.moflo/daemon.lock` when the daemon starts — if the deterministic port is already taken the daemon scans forward, so the lock file is the source of truth, not the hash.
-
-Three ways to get the URL:
-
-- **`/luminarium`** — inside a Claude Code session in a moflo project, this skill reads `.moflo/daemon.lock` and prints `http://localhost:<port>`. Fastest path.
-- **`flo daemon status`** — prints the URL alongside the health summary.
-- **`cat .moflo/daemon.lock`** — read the JSON directly: `{ "pid": ..., "port": 33421, ... }`.
+Inside a Claude Code session in a moflo project, ask **`/luminarium`** — the skill prints the dashboard URL for the current project. `flo daemon status` prints the same URL alongside the health summary. Each project binds its own port so two projects on the same machine never collide.
 
 ### What it shows
 
@@ -486,7 +480,7 @@ Three ways to get the URL:
 ### Flags
 
 - `flo daemon start --no-dashboard` — disable the HTTP server entirely (the daemon itself still runs)
-- `flo daemon start --dashboard-port <N>` — pin to a specific port, overriding the deterministic resolver. Also accepts the `MOFLO_DAEMON_PORT` env var, which the rest of moflo respects when talking to the daemon
+- `flo daemon start --dashboard-port <N>` — pin to a specific port, overriding the per-project default. Also accepts the `MOFLO_DAEMON_PORT` env var, which the rest of moflo respects when talking to the daemon
 
 ## Commands
 

package/dist/src/cli/services/headless-worker-executor.js

@@ -90,7 +90,7 @@ Provide actionable suggestions with code examples.`,
 - Check for missing error handling tests
 - Identify integration test gaps
 
-For each gap, provide a test skeleton.`,
+For each gap, include a test skeleton inline in the report as a fenced code block — DO NOT create separate test files; the consumer will copy the skeletons into their test tree by hand.`,
             sandbox: 'permissive',
             model: 'sonnet',
             outputFormat: 'markdown',
@@ -300,11 +300,13 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             maxContextFiles: options?.maxContextFiles ?? 20,
             maxCharsPerFile: options?.maxCharsPerFile ?? 5000,
             logDir: options?.logDir ?? join(projectRoot, '.moflo', 'logs', 'headless'),
+            reportsDir: options?.reportsDir ?? join(projectRoot, '.moflo', 'reports'),
             cacheContext: options?.cacheContext ?? true,
             cacheTtlMs: options?.cacheTtlMs ?? 60000, // 1 minute default
         };
-        // Ensure log directory exists
+        // Ensure log + reports directories exist
         this.ensureLogDir();
+        this.ensureReportsDir();
         // Register for process-exit cleanup via the shared listener.
         ensureExitListener();
         liveExecutors.add(this);
@@ -546,6 +548,29 @@ export class HeadlessWorkerExecutor extends EventEmitter {
             this.emit('warning', { message: 'Failed to create log directory', error });
         }
     }
+    /**
+     * Ensure the reports directory exists. Reports land under `.moflo/reports/`
+     * (gitignored by `flo init`); without this directory the post-spawn write
+     * would no-op and the consumer would lose the report entirely.
+     */
+    ensureReportsDir() {
+        try {
+            if (!existsSync(this.config.reportsDir)) {
+                mkdirSync(this.config.reportsDir, { recursive: true });
+            }
+        }
+        catch (error) {
+            this.emit('warning', { message: 'Failed to create reports directory', error });
+        }
+    }
+    /**
+     * Resolve the on-disk report path for a worker. Extension matches the
+     * declared outputFormat so tools reading the report don't have to sniff.
+     */
+    getReportPath(workerType, outputFormat) {
+        const ext = outputFormat === 'json' ? 'json' : outputFormat === 'text' ? 'txt' : 'md';
+        return join(this.config.reportsDir, `${workerType}.${ext}`);
+    }
     /**
      * Internal execution logic
      */
@@ -558,8 +583,11 @@ export class HeadlessWorkerExecutor extends EventEmitter {
         try {
             // Build context from file patterns
             const context = await this.buildContext(headless.contextPatterns || []);
+            // Resolve the on-disk report path before prompt assembly so the prompt
+            // can quote the exact absolute path Claude should write to.
+            const reportPath = this.getReportPath(workerType, headless.outputFormat);
             // Build the full prompt
-            const fullPrompt = this.buildPrompt(headless.promptTemplate, context);
+            const fullPrompt = this.buildPrompt(headless.promptTemplate, context, reportPath);
             // Log prompt for debugging
             this.logExecution(executionId, 'prompt', fullPrompt);
             // Execute Claude Code headlessly
@@ -571,6 +599,13 @@ export class HeadlessWorkerExecutor extends EventEmitter {
                 workerType,
                 signal,
             });
+            // Persist the spawn output to the canonical report path. Belt-and-braces
+            // against Claude ignoring the in-prompt instruction — this guarantees
+            // the consumer ends up with a report at a deterministic location no
+            // matter what the model chose to do with its Write tool.
+            if (result.success && result.output && result.output.trim().length > 0) {
+                this.writeReport(reportPath, result.output);
+            }
             // Parse output based on format
             let parsedOutput;
             if (headless.outputFormat === 'json' && result.output) {
@@ -768,15 +803,23 @@ export class HeadlessWorkerExecutor extends EventEmitter {
         return name === pattern;
     }
     /**
-     * Build full prompt with context
+     * Build full prompt with context. The report path is injected so Claude
+     * saves output to the canonical `.moflo/reports/` location instead of
+     * dropping `*-analysis.md` / `*-report.md` files at the project root — the
+     * behaviour consumers were seeing before this change.
      */
-    buildPrompt(template, context) {
+    buildPrompt(template, context, reportPath) {
+        const ioInstructions = `## Output
+
+Save the full report to \`${reportPath}\` using the Write tool. Overwrite any prior content at that path. DO NOT create any other files anywhere in the project; if you need to suggest test skeletons or code samples, include them inline in the report as fenced code blocks. Moflo persists the same output to that path after you finish, so the location is authoritative.`;
         if (!context) {
             return `${template}
 
 ## Instructions
 
-Analyze the codebase and provide your response following the format specified in the task.`;
+Analyze the codebase and provide your response following the format specified in the task.
+
+${ioInstructions}`;
         }
         return `${template}
 
@@ -786,7 +829,9 @@ ${context}
 
 ## Instructions
 
-Analyze the above codebase context and provide your response following the format specified in the task.`;
+Analyze the above codebase context and provide your response following the format specified in the task.
+
+${ioInstructions}`;
     }
     /**
      * Execute Claude Code in headless mode
@@ -1011,6 +1056,22 @@ Analyze the above codebase context and provide your response following the forma
             // Ignore log write errors
         }
     }
+    /**
+     * Persist a worker's report to the canonical `.moflo/reports/` location.
+     * The directory was created at construction time; we recreate it here as a
+     * safety net in case it was removed between construction and execution.
+     */
+    writeReport(reportPath, content) {
+        try {
+            if (!existsSync(this.config.reportsDir)) {
+                mkdirSync(this.config.reportsDir, { recursive: true });
+            }
+            writeFileSync(reportPath, content);
+        }
+        catch (error) {
+            this.emit('warning', { message: 'Failed to write worker report', reportPath, error });
+        }
+    }
 }
 // Export default
 export default HeadlessWorkerExecutor;

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.14",
+  "version": "4.10.16",
   "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.13",
+    "moflo": "^4.10.15",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"