moflo 4.10.13 → 4.10.15

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/commands/doctor-checks-config.js

@@ -425,13 +425,10 @@ export async function checkNestedMofloIslands(cwd) {
     }
     const { islands, truncated } = scan;
     if (islands.length === 0) {
-        const baseMsg = 'No nested .moflo/ directories detected';
         return {
             name: 'Nested .moflo/ Islands',
-            status: truncated ? 'warn' : 'pass',
-            message: truncated
-                ? `${baseMsg} within depth-5 walk — deeper subtrees not inspected`
-                : baseMsg,
+            status: 'pass',
+            message: 'No nested .moflo/ directories detected',
         };
     }
     const rels = islands.map(p => relative(root, p) || '.');

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

package/package.json

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