moflo 4.11.7 → 4.11.8

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

package/package.json

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