moflo 4.11.6 → 4.11.8

package/.claude/guidance/shipped/moflo-memory-protocol.md

@@ -4,7 +4,7 @@
 
 ## Rule (MUST)
 
-When a search hit carries a non-null `navigation` field, you MUST traverse via `mcp__moflo__memory_get_neighbors` — NOT bulk-retrieve every hit with `memory_retrieve`. The `navigation` crumb is the chunking architecture's contract; bulk-retrieving every search hit defeats it and is a protocol violation. Use `memory_retrieve` only for a single specific key you already hold, or for non-chunk entries where `navigation` is null.
+When a search hit carries a non-null `navigation` field and you need adjacent context, prefer `memory_search` with `expand: 'neighbors'` — it inlines each chunk hit's prev/next content in the SAME call (one round-trip, no re-embedding). Otherwise traverse via `mcp__moflo__memory_get_neighbors`. NEVER bulk-retrieve every hit with `memory_retrieve` — the `navigation` crumb is the chunking architecture's contract, and bulk-retrieving defeats it (protocol violation). NEVER `Read` a chunk's `parentPath` for surrounding context when `expand`/neighbors would do — a full-doc Read costs far more tokens. Use `memory_retrieve` only for a single specific key you already hold, or for non-chunk entries where `navigation` is null.
 
 ---
 
@@ -146,7 +146,8 @@ Once you have a search hit, pick the right follow-up call by what you need next.
 | You want | Use | Why |
 |----------|-----|-----|
 | Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with `navigation` (parentDoc, prev/next, chunkTitle) |
-| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, shaped entries with full nav |
+| Adjacent context AND you're still searching | `mcp__moflo__memory_search` `{ query, expand: 'neighbors' }` | Cheapest — prev/next content inlined in the search call itself, zero extra round-trips |
+| Adjacent context for a hit you already have | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, shaped entries with full nav |
 | Same-section peers (h2/h3 family) | `memory_get_neighbors` `{ include: ['siblings'] }` or `['parent','children']` | Hierarchical traversal — cheaper than re-searching |
 | Full content of one specific chunk | `mcp__moflo__memory_retrieve` `{ key }` | For a key you already hold — never for bulk-retrieving search hits |
 | Whole source doc when truly needed | `Read` `parentPath` from any chunk's nav | Disk read is cheaper than re-indexed `doc-*` |

package/.claude/skills/fl/phases.md

@@ -224,6 +224,14 @@ gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for
 gh issue comment <issue-number> --body "PR created: <pr-url>"
 ```
 
+If the story body carries an `Epic: #<n>` back-reference (decomposition writes it — `./ticket.md`) **and** `--epic-branch` is not set, sync the parent epic — check this story's box off and close the epic if it was the last:
+
+```bash
+flo epic checkoff <epic-number> <story-number>
+```
+
+Idempotent and safe to skip when there is no back-reference. `--epic-branch` runs skip it — the epic orchestrator owns checklist state there. The box flips when the work is delivered (PR opened), matching the orchestrator; if a PR is later rejected, reopen the epic manually.
+
 ### 5.5 Finalize run record (Flo Runs dashboard)
 
 Update the tasklist row written in Phase 0 with the terminal status. Same `runId`, `upsert: true`. On success:

package/.claude/skills/fl/ticket.md

@@ -35,25 +35,47 @@ When promoting to epic:
 2. Each story should be completable in a single PR.
 3. Stories should have clear boundaries (one concern per story).
 4. Order stories by dependency (independent ones first).
-5. Create each story as a GitHub issue with its own Description, Acceptance Criteria, and Test Cases.
-6. Convert the parent issue into an epic with a `## Stories` checklist.
+5. Establish the epic issue **first** so its number exists before the stories do (either the promoted parent issue or a freshly created epic).
+6. Create each story as a GitHub issue with its own Description, Acceptance Criteria, Test Cases, **and an `Epic: #<epic-number>` back-reference line at the top of the body**.
+7. Fill in the epic's `## Stories` checklist with a `- [ ] #<story-number>` line for every story.
+
+The **back-reference is load-bearing**, not decoration: a story is usually worked on later via a standalone `/flo <story>` run, not through `flo epic run`. That standalone run reads the `Epic: #<n>` line to find its parent, check its box off, and close the epic when it is the last story. Without the back-reference the epic silently drifts out of sync — the exact miss this step exists to prevent. See `./phases.md` Phase 5.6.
 
 ## Epic decomposition (score >= 7)
 
+The order matters: the epic must exist before the stories so each story can carry the `Epic: #<n>` back-reference, and the epic's checklist is filled in last.
+
+Pass multi-line bodies as a single literal `--body "..."` string (portable — no `printf`/heredoc, which are not guaranteed on every consumer OS; Rule #1). For very large bodies write the text to a file with the Write tool and use `--body-file <path>`.
+
 ```bash
-# Step 1: create each sub-issue
-gh issue create --title "Story: <story-title>" --body "<## Description + ## Acceptance Criteria + ## Suggested Test Cases>" --label "story"
-# capture the new issue number from output
+# Step 1: establish the epic issue and capture its number (EPIC).
+#   Promoting an existing issue — it *is* the epic; add the label now:
+gh issue edit <parent-number> --add-label "epic"            # EPIC = <parent-number>
+#   Or create a fresh epic with an empty Stories section:
+gh issue create --title "Epic: <title>" --label "epic" --body "<## Overview + empty ## Stories section>"
+# capture EPIC = the epic issue number from whichever path above
+
+# Step 2: create each story WITH the Epic back-reference as the first line; capture each number.
+#   (repeat for all stories, typically 2–6)
+gh issue create --title "Story: <story-title>" --label "story" --body "<Epic: #<EPIC> + ## Description + ## Acceptance Criteria + ## Suggested Test Cases>"
+
+# Step 3: fill the epic's ## Stories checklist with a - [ ] #<story> line per story.
+gh issue edit <EPIC> --body "<epic body with the ## Stories checklist filled in>"
+```
+
+**Story body format** — the first line is the back-reference; the standalone `/flo <story>` run (`./phases.md` Phase 5.6) parses `Epic: #<n>` from it:
 
-# Step 2: repeat for all stories (typically 2–6)
+```markdown
+Epic: #<epic-number>
 
-# Step 3: build the epic body with a checklist referencing every story number
+## Description
+<what and why>
 
-# Step 4: update an existing issue into an epic
-gh issue edit <parent-number> --add-label "epic" --body "<epic body with ## Stories checklist>"
+## Acceptance Criteria
+- [ ] ...
 
-# Step 5: or create a new epic
-gh issue create --title "Epic: <title>" --label "epic" --body "<epic body>"
+## Suggested Test Cases
+- ...
 ```
 
 **Epic body format** — the `## Stories` checklist with `- [ ] #<number>` is what enables epic detection, story extraction, and progress tracking:

package/dist/src/cli/commands/epic.js

@@ -12,11 +12,12 @@
  *   flo epic run 42 --verbose                Echo each step's stdout/stderr after it completes
  *   flo epic status <epic-number>            Check progress via memory
  *   flo epic reset <epic-number>             Clear epic memory state
+ *   flo epic checkoff <epic> <story>         Check a story off; close the epic if it was the last
  */
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
-import { isEpicIssue, fetchEpicIssue, extractStories, enrichStoryNames, } from '../epic/index.js';
+import { isEpicIssue, fetchEpicIssue, extractStories, enrichStoryNames, checkOffStoryInEpic, } from '../epic/index.js';
 import { runEpicSpell, } from '../epic/runner-adapter.js';
 import { locateMofloModulePath } from '../services/moflo-require.js';
 import { select } from '../prompt.js';
@@ -362,6 +363,36 @@ async function resetEpic(epicNumber) {
     return { success: true };
 }
 // ============================================================================
+// Subcommand: checkoff
+// ============================================================================
+async function checkOffStory(epicArg, storyArg) {
+    const epic = parseInt(epicArg, 10);
+    const story = parseInt(storyArg, 10);
+    if (isNaN(epic) || isNaN(story)) {
+        return { success: false, message: 'Usage: flo epic checkoff <epic-number> <story-number>' };
+    }
+    try {
+        const { checked, epicClosed, alreadyClosed } = await checkOffStoryInEpic(epic, story);
+        const parts = [];
+        parts.push(checked
+            ? `Checked off story #${story} in epic #${epic}.`
+            : `Story #${story} was already checked (or not listed) in epic #${epic}.`);
+        if (epicClosed)
+            parts.push(`All stories complete — closed epic #${epic}.`);
+        else if (alreadyClosed)
+            parts.push(`Epic #${epic} was already closed.`);
+        const message = parts.join(' ');
+        console.log(`[epic] ${message}`);
+        return { success: true, message };
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: buildFailureSummary(err.message, { stepId: 'checkoff' }),
+        };
+    }
+}
+// ============================================================================
 // Preflight warning interactive resolver
 // ============================================================================
 function isInteractive() {
@@ -461,6 +492,7 @@ const epicCommand = {
         { command: 'flo epic run 42', description: 'Explicit run subcommand (same as above)' },
         { command: 'flo epic status 42', description: 'Check epic progress' },
         { command: 'flo epic reset 42', description: 'Reset epic state for re-run' },
+        { command: 'flo epic checkoff 42 43', description: 'Check story #43 off in epic #42; close #42 if it was the last story' },
     ],
     action: async (ctx) => {
         const subcommand = ctx.args?.[0];
@@ -469,10 +501,11 @@ const epicCommand = {
             console.log('       flo epic <command> [args] [flags]');
             console.log('');
             console.log('Commands:');
-            console.log('  <issue-number>           Execute epic (shorthand for "run")');
-            console.log('  run <issue-number>       Execute a GitHub epic via spell engine');
-            console.log('  status <epic-number>     Check epic progress');
-            console.log('  reset <epic-number>      Reset epic state for re-run');
+            console.log('  <issue-number>              Execute epic (shorthand for "run")');
+            console.log('  run <issue-number>          Execute a GitHub epic via spell engine');
+            console.log('  status <epic-number>        Check epic progress');
+            console.log('  reset <epic-number>         Reset epic state for re-run');
+            console.log('  checkoff <epic> <story>     Check a story off in its epic; close the epic if it was the last');
             console.log('');
             console.log('Flags:');
             console.log('  --strategy <name>        single-branch (default) or auto-merge');
@@ -518,8 +551,10 @@ const epicCommand = {
                 return showStatus(commandArgs[0] || '');
             case 'reset':
                 return resetEpic(commandArgs[0] || '');
+            case 'checkoff':
+                return checkOffStory(commandArgs[0] || '', commandArgs[1] || '');
             default:
-                return { success: false, message: `Unknown subcommand: ${subcommand}. Available: run, status, reset` };
+                return { success: false, message: `Unknown subcommand: ${subcommand}. Available: run, status, reset, checkoff` };
         }
     },
 };

package/dist/src/cli/epic/detection.js

@@ -6,7 +6,7 @@
  *
  * Story #195: Shared epic detection & extraction module.
  */
-import { exec } from 'node:child_process';
+import { exec, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
 const execAsync = promisify(exec);
 // ============================================================================
@@ -138,4 +138,59 @@ export async function findPrForIssue(issueNumber) {
         return null;
     }
 }
+// ============================================================================
+// Story checkoff (standalone `/flo <story>` runs)
+// ============================================================================
+/**
+ * Pure core of the story-checkoff operation — no I/O, unit-testable.
+ *
+ * Flips a story's `- [ ] #<n>` checkbox to `- [x] #<n>` in an epic body and
+ * reports whether the epic is now complete (it has story checkboxes and none
+ * remain unchecked). Word-boundary guarded so #12 never matches inside #123.
+ */
+export function computeEpicCheckoff(body, storyNumber) {
+    const pattern = new RegExp(`- \\[ \\] #${storyNumber}(?!\\d)`);
+    const updated = body.replace(pattern, `- [x] #${storyNumber}`);
+    const checked = updated !== body;
+    const hasStoryCheckboxes = /- \[[ x]\] #\d+/.test(updated);
+    const hasUnchecked = /- \[ \] #\d+/.test(updated);
+    const allComplete = hasStoryCheckboxes && !hasUnchecked;
+    return { updated, checked, allComplete };
+}
+/**
+ * Check a story off in its parent epic's checklist, and close the epic when no
+ * unchecked stories remain. Used by standalone `/flo <story>` runs via
+ * `flo epic checkoff`; the orchestrated `flo epic run` path does its own
+ * checkoff inside the spell (epic-single-branch.yaml).
+ *
+ * Cross-platform (Rule #1): drives `gh` through `spawnSync` arg arrays (no
+ * shell string to escape) and pipes the rewritten body over stdin
+ * (`--body-file -`), the same pattern proven on Windows CI in the spell.
+ */
+export async function checkOffStoryInEpic(epicNumber, storyNumber) {
+    const issue = await fetchEpicIssue(epicNumber);
+    const { updated, checked, allComplete } = computeEpicCheckoff(issue.body || '', storyNumber);
+    if (checked) {
+        const edit = spawnSync('gh', ['issue', 'edit', String(epicNumber), '--body-file', '-'], {
+            input: updated,
+            encoding: 'utf8',
+        });
+        if (edit.status !== 0) {
+            throw new Error(`gh issue edit failed: ${(edit.stderr || edit.error?.message || 'unknown').toString().trim()}`);
+        }
+    }
+    const alreadyClosed = issue.state.toUpperCase() === 'CLOSED';
+    const epicClosed = allComplete && !alreadyClosed;
+    if (epicClosed) {
+        const close = spawnSync('gh', [
+            'issue', 'close', String(epicNumber),
+            '--reason', 'completed',
+            '--comment', `All stories complete — closed automatically after story #${storyNumber}.`,
+        ], { encoding: 'utf8' });
+        if (close.status !== 0) {
+            throw new Error(`gh issue close failed: ${(close.stderr || close.error?.message || 'unknown').toString().trim()}`);
+        }
+    }
+    return { checked, epicClosed, alreadyClosed };
+}
 //# sourceMappingURL=detection.js.map

package/dist/src/cli/epic/index.js

@@ -3,5 +3,5 @@
  *
  * Story #195: Shared epic detection & extraction module.
  */
-export { isEpicIssue, extractStories, extractUncheckedStories, fetchEpicIssue, enrichStoryNames, findPrForIssue, } from './detection.js';
+export { isEpicIssue, extractStories, extractUncheckedStories, fetchEpicIssue, enrichStoryNames, findPrForIssue, computeEpicCheckoff, checkOffStoryInEpic, } from './detection.js';
 //# sourceMappingURL=index.js.map

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

@@ -90,6 +90,20 @@ function parseNavigation(metadataJson, mode) {
         headerLevel: meta.headerLevel,
     };
 }
+// #1262 lever #1 (dedup-by-source): collapse multiple representations of the
+// SAME underlying source to one result slot. Dogfooding showed a dense query's
+// top-8 is routinely ~40% duplicates — e.g. one file indexed in code-map as
+// `file:<path>` AND in patterns as `pattern:file:<path>`, or a test surfaced as
+// both `file:<path>` and `test-file:<path>`. Path-bearing keys reduce to their
+// path; symbol/chunk/learning keys keep their own identity (a `pattern:class:X`
+// symbol view is NOT the same source as the file, so it survives separately).
+// Operates purely on logical DB keys (always forward-slash), so platform-agnostic.
+function sourceIdOf(key) {
+    const pathMatch = key.match(/^(?:pattern:)?(?:file|test-file|dir):(.+)$/);
+    if (pathMatch)
+        return `src:${pathMatch[1]}`;
+    return key.startsWith('pattern:') ? key.slice('pattern:'.length) : key;
+}
 function shapeRetrievedEntry(entry) {
     let value = entry.content;
     try {
@@ -325,39 +339,53 @@ export const memoryTools = [
     },
     {
         name: 'memory_search',
-        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search). When a result has a non-null `navigation` crumb, you MUST traverse via `memory_get_neighbors` — bulk `memory_retrieve` per hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.',
+        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search). On chunk hits (non-null `navigation`) you MUST get adjacent context via chunk traversal, never a full-doc `Read`: prefer `expand: "neighbors"` in THIS call (cheapest — inlines prev/next), else `memory_get_neighbors`. Bulk `memory_retrieve` per hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.',
         category: 'memory',
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query (semantic similarity)' },
                 namespace: { type: 'string', description: 'Namespace to search (default: all namespaces)' },
-                limit: { type: 'number', description: 'Maximum results (default: 8)' },
+                limit: { type: 'number', description: 'Maximum results (default: 8). Multiple representations of the same source (a file indexed in both code-map and patterns, a test surfaced as both file and test-file) are collapsed to one before this cap, so every slot is a distinct source.' },
                 threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.5)' },
+                expand: {
+                    type: 'string',
+                    enum: ['neighbors'],
+                    description: "Set to 'neighbors' to inline each chunk hit's adjacent (prev/next) chunk content in this single call. Use instead of a follow-up full-doc `Read` when you need surrounding context. Off by default to keep the envelope lean.",
+                },
             },
             required: ['query'],
         },
         handler: async (input) => {
             await ensureInitialized();
-            const { searchEntries } = await getMemoryFunctions();
+            const { searchEntries, getEntry } = await getMemoryFunctions();
             const query = input.query;
             const namespace = input.namespace || 'all';
-            // #1053 S6: tighter defaults — fewer hits, higher relevance bar.
+            // #1053 S6: injected-token bar. Each returned hit is injected verbatim,
+            // so keep the cap tight — but #1262 dedup (below) makes every one of these
+            // slots a DISTINCT source rather than 8 slots holding ~5 uniques + dupes.
             const limit = input.limit || 8;
             // Falsiness check would coerce a caller-supplied 0 to default and silently
             // filter low-similarity matches; use a typeof guard so explicit zero
             // means "no threshold" (#837).
             const threshold = typeof input.threshold === 'number' ? input.threshold : 0.5;
+            // #1262 lever #3: opt-in single-call neighbor expansion.
+            const wantExpand = input.expand === 'neighbors' || input.expand === true;
+            // #1262 lever #1: over-fetch so dedup-by-source can still return a FULL
+            // `limit` distinct sources. Local HNSW makes the extra hits free (they're
+            // just not injected); 3x headroom clears the ~40% duplication observed in
+            // dogfooding. Capped so an explicit large limit can't blow up the fetch.
+            const overscan = Math.min(limit * 3, 50);
             validateMemoryInput(undefined, undefined, query);
             try {
                 const result = await searchEntries({
                     query,
                     namespace,
-                    limit,
+                    limit: overscan,
                     threshold,
                 });
                 // Parse JSON values in results
-                const results = result.results.map(r => {
+                const mapped = result.results.map(r => {
                     let value = r.content;
                     try {
                         value = JSON.parse(r.content);
@@ -379,13 +407,67 @@ export const memoryTools = [
                         navigation,
                     };
                 });
+                // #1262 lever #1: collapse duplicate representations of the same source,
+                // keeping the highest-scoring one (results arrive score-desc), then trim
+                // to `limit`. Net effect vs. the old code: `limit` DISTINCT sources
+                // instead of `limit` slots that were often ~40% near-duplicates.
+                const seenSources = new Set();
+                const results = [];
+                for (const hit of mapped) {
+                    const id = sourceIdOf(hit.key);
+                    if (seenSources.has(id))
+                        continue;
+                    seenSources.add(id);
+                    results.push(hit);
+                    if (results.length >= limit)
+                        break;
+                }
+                // #1262 lever #3: when asked, fetch each chunk hit's prev/next content
+                // inline (one round-trip) so the model doesn't fall back to a full-doc
+                // `Read` for surrounding context. Opt-in keeps the default lean.
+                if (wantExpand) {
+                    await Promise.all(results.map(async (hit) => {
+                        const nav = hit.navigation;
+                        if (!nav)
+                            return; // non-chunk hit — nothing adjacent to fetch
+                        const targets = [
+                            { position: 'prev', key: nav.prevChunk },
+                            { position: 'next', key: nav.nextChunk },
+                        ].filter((t) => Boolean(t.key));
+                        if (targets.length === 0)
+                            return;
+                        const fetched = await Promise.all(targets.map(async (t) => {
+                            const res = await getEntry({ key: t.key, namespace: hit.namespace });
+                            if (!res.found || !res.entry)
+                                return null;
+                            const entry = res.entry;
+                            let value = entry.content;
+                            try {
+                                value = JSON.parse(entry.content);
+                            }
+                            catch { /* keep string */ }
+                            return { position: t.position, key: t.key, value };
+                        }));
+                        const neighbors = fetched.filter((n) => n !== null);
+                        if (neighbors.length > 0)
+                            hit.expanded = neighbors;
+                    }));
+                }
                 notifyMemoryGate();
+                // #1262 lever #3: steer away from full-doc `Read` toward the cheap
+                // adjacent-context path — but only when it's actionable (chunk hits
+                // present and the caller didn't already expand), so the hint itself
+                // costs no tokens on the common case.
+                const nextStep = !wantExpand && results.some(r => r.navigation)
+                    ? "Chunk hits present. For adjacent context, re-call memory_search with expand:'neighbors' (one call) rather than Read-ing parentPath — full-doc Read costs far more tokens."
+                    : undefined;
                 // #1053 S6: searchTime dropped from MCP envelope (CLI keeps it for
                 // human reading); `backend` retained — doctor reads it (#1053 epic).
                 return {
                     query,
                     results,
                     total: results.length,
+                    ...(nextStep ? { nextStep } : {}),
                     backend: BACKEND_LABEL,
                 };
             }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.11.6",
+  "version": "4.11.8",
   "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",
@@ -94,7 +94,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.11.5",
+    "moflo": "^4.11.7",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"