moflo 4.8.56-rc.9 → 4.8.57

package/.claude/guidance/shipped/moflo-user-facing-language.md

@@ -0,0 +1,34 @@
+# User-Facing Language Guidelines
+
+**Purpose:** Ensure all text shown to end users is approachable and non-alarming. MoFlo is used by developers and non-technical users alike — the language we use in output, prompts, reports, and error messages must be clear to someone who has never written code.
+
+---
+
+## Principles
+
+1. **Avoid technical jargon in user-visible output.** Terms like "destructive", "mutation", "elevated privileges", or "sandbox escape" are meaningful to engineers but alarming or confusing to non-technical users. Prefer plain risk-level language: "No risk", "Low risk", "Moderate risk", "Higher risk".
+
+2. **Explain what happens, not the mechanism.** Instead of "shell command execution", say "Runs commands on your machine". Instead of "fs:write capability", say "Creates, overwrites, or deletes files".
+
+3. **Reserve technical terms for internal code.** Type names, variable names, config keys, log prefixes, and developer documentation can use precise technical language. The boundary is: if the user sees it, simplify it.
+
+4. **Err on the side of calm.** When something requires attention, state the facts without dramatizing. "This step modifies files" is better than "WARNING: DESTRUCTIVE OPERATION DETECTED".
+
+---
+
+## Where This Applies
+
+- Permission disclosure / risk analysis reports
+- Error messages shown to users (not debug logs)
+- CLI output and status messages
+- MCP tool descriptions and response messages
+- Spell dry-run and acceptance gate output
+- Any `console.log` that a user will see during normal operation
+
+## Where This Does NOT Apply
+
+- Internal type definitions and variable names
+- Developer-facing config keys (e.g., `allowDestructive` in spell YAML)
+- Debug/trace logs gated behind verbose flags
+- Code comments and docstrings
+- Test descriptions

package/.claude/skills/connector-builder/SKILL.md

@@ -414,6 +414,46 @@ export const <type>Command: StepCommand<<Type>StepConfig> = {
     ];
   },
 
+  // Optional: runtime preflight checks — run BEFORE any step executes.
+  // Use for validating runtime state (issue open, service reachable, etc).
+  // CRITICAL: the `reason` string IS the message the end user sees.
+  // Write it in plain English. State the problem AND the fix. No tool
+  // jargon, no exit codes, no internal identifiers.
+  //
+  // Default severity is 'fatal' (abort on failure). Set severity: 'warning'
+  // + resolutions when the user can safely choose how to proceed; in
+  // interactive runs they'll be prompted, in non-interactive runs warnings
+  // behave like fatals.
+  //
+  // preflight: [
+  //   {
+  //     name: '<service> reachable',
+  //     severity: 'fatal',
+  //     check: async (config, ctx) => {
+  //       const ok = await ping(config.endpoint);
+  //       if (ok) return { passed: true };
+  //       return {
+  //         passed: false,
+  //         reason: `Can't reach ${config.endpoint}. Check your network connection or the service URL in your spell config.`,
+  //       };
+  //     },
+  //   },
+  //   {
+  //     name: 'local cache fresh',
+  //     severity: 'warning',
+  //     resolutions: [
+  //       { label: 'Refresh the cache now', command: '<type>-cli cache refresh' },
+  //       { label: 'Continue with stale cache' },
+  //     ],
+  //     check: async (config) => {
+  //       const stale = await isCacheStale(config.endpoint);
+  //       return stale
+  //         ? { passed: false, reason: 'Your local cache is more than 24 hours old and may produce outdated results.' }
+  //         : { passed: true };
+  //     },
+  //   },
+  // ],
+
   // Optional: rollback on failure
   // async rollback(config, context) { /* undo side effects */ },
 };
@@ -421,6 +461,18 @@ export const <type>Command: StepCommand<<Type>StepConfig> = {
 
 Alternatively, use the `createStepCommand()` factory from `src/modules/spells/src/commands/create-step-command.ts` for compile-time type safety.
 
+#### Preflight `reason` strings — write for humans
+
+When your step declares `preflight` checks, the `reason` string returned on failure is shown verbatim to end users as the error message. Treat it as user-facing copy:
+
+- Plain English, no command names, exit codes, or internal identifiers.
+- State BOTH the problem and the fix.
+- Assume a non-technical reader.
+
+Good: `"You're not signed in to GitHub. Run: gh auth login"`
+Bad: `"gh auth status exited with code 1"` — leaks implementation detail
+Bad: `"auth check failed"` — tells the user nothing actionable
+
 ### Step 3: Generate Step Command Test
 
 Create at `tests/packages/spells/commands/<type>-command.test.ts`:

package/.claude/skills/publish/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: publish
+description: Bump version, build, test, publish to npm, and install locally
+arguments: "[patch|minor|major] [-rc]"
+---
+
+# /publish - Version Bump, Build, Test & Publish
+
+Automated release pipeline for moflo. Bumps version, commits, builds, tests, runs doctor, publishes to npm, and installs the new version locally.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/publish              # patch bump (4.8.56 → 4.8.57)
+/publish minor        # minor bump (4.8.56 → 4.9.0)
+/publish major        # major bump (4.8.56 → 5.0.0)
+/publish -rc          # patch RC bump (4.8.56 → 4.8.57-rc.1, or 4.8.57-rc.1 → 4.8.57-rc.2)
+/publish minor -rc    # minor RC bump (4.8.56 → 4.9.0-rc.1)
+/publish patch        # explicit patch bump
+```
+
+## Step-by-Step Procedure
+
+Follow docs/BUILD.md exactly. Every step must succeed before proceeding to the next.
+
+### Step 1: Parse Arguments
+
+- Default bump type is `patch` if not specified
+- If `-rc` flag is present, produce a release candidate version
+- Determine the new version string:
+  - **Without `-rc`:** Use `npm version <patch|minor|major> --no-git-tag-version`
+  - **With `-rc`:** Calculate manually:
+    - If current version is already an RC of the same bump level (e.g., `4.8.57-rc.3`), increment the RC number (→ `4.8.57-rc.4`)
+    - Otherwise, bump the base version and append `-rc.1` (e.g., `4.8.56` → `4.8.57-rc.1`)
+    - Write with: `npm version <new-version> --no-git-tag-version`
+
+### Step 2: Rebuild After Version Bump
+
+```bash
+npm run build
+```
+
+This syncs the version to `src/modules/cli/src/version.ts` and `src/modules/cli/package.json` via the `version` lifecycle script, then compiles all TypeScript.
+
+**Must exit 0.** If it fails, stop and fix the build error.
+
+### Step 3: Run Tests
+
+```bash
+npm test
+```
+
+**Must have 0 test file failures.** If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken window theory). Fix all real failures before proceeding.
+
+### Step 4: Run Doctor
+
+```bash
+npx moflo doctor --fix
+```
+
+All checks must pass (warnings are acceptable on Windows for sandbox tier). If doctor finds fixable issues, it will auto-fix them. If manual fixes are needed, stop and address them.
+
+### Step 5: Commit & Push
+
+Commit the version bump files:
+
+```bash
+git add package.json package-lock.json src/modules/cli/package.json src/modules/cli/src/version.ts
+git commit -m "chore: bump version to <new-version>"
+git push origin main
+```
+
+Only commit version-related files. Do not stage unrelated changes.
+
+### Step 6: Verify npm Authentication
+
+Before publishing, verify npm auth is valid:
+
+```bash
+npm whoami
+```
+
+If this returns a 401 or "not logged in" error, the auth token in `~/.npmrc` is missing or expired. Ask the user to provide a valid npm publish token.
+
+**How to create a token** (provide these instructions to the user if needed):
+1. Go to https://www.npmjs.com/settings/~/tokens
+2. Click "Generate New Token" → select "Granular Access Token"
+3. Set permissions: "Read and write" for the `moflo` package
+4. Copy the token (starts with `npm_...`)
+
+Once the user provides the token, write it to `~/.npmrc`:
+
+```bash
+echo "//registry.npmjs.org/:_authToken=<token>" > ~/.npmrc
+```
+
+Then verify with `npm whoami` before proceeding.
+
+### Step 7: Publish to npm
+
+```bash
+npm publish --tag <tag>
+```
+
+- For stable releases: `npm publish` (publishes to `latest` tag by default)
+- For RC releases: `npm publish --tag rc` (publishes to `rc` tag so it doesn't become `latest`)
+
+**OTP handling:**
+- If npm returns an OTP/one-time-password error, ask the user for their authenticator code
+- Then retry with: `npm publish --otp=<code> --tag <tag>`
+- Tip: Granular access tokens created on npmjs.com do NOT require OTP — prefer those over legacy tokens
+
+### Step 8: Verify Publication
+
+```bash
+npm view moflo version
+npm view moflo dist-tags
+```
+
+Confirm the published version matches what we just built.
+
+### Step 9: Install Locally
+
+```bash
+npm install moflo@<new-version> --save-dev
+```
+
+This updates `package.json` and `package-lock.json` to use the newly published version as a devDependency.
+
+### Step 10: Final Commit
+
+If `package.json` or `package-lock.json` changed from the install:
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore: install moflo@<new-version>"
+git push origin main
+```
+
+## Output
+
+Print a summary at the end:
+
+```
+Publish Summary
+───────────────
+Version:    <old> → <new>
+Tag:        latest | rc
+Build:      passed
+Tests:      <N> files passed, <N> tests passed
+Doctor:     <N> passed, <N> warnings
+Published:  moflo@<new-version>
+Installed:  moflo@<new-version> (devDependency)
+```
+
+## Important
+
+- All commands run from the project root — never cd into subdirectories
+- Never use `--force` on npm publish
+- Never install moflo globally — it is always a local devDependency
+- If any step fails, stop and fix the issue before proceeding — do not skip steps
+- The `prepublishOnly` script in package.json runs `check-version-sync.mjs && npm run build` automatically, so npm publish will fail-fast if versions are out of sync

package/.claude/skills/reset-epic/SKILL.md

@@ -26,7 +26,8 @@ Given an epic issue number, perform ALL of the following:
 4. **Delete local branches**: Delete any local branches matching the same patterns (skip the current branch)
 5. **Reopen issues**: Reopen all story issues and the epic itself if any were closed
 6. **Uncheck task lists**: Edit the epic body to uncheck all `- [x]` checkboxes back to `- [ ]`
-7. **Verify clean state**: Confirm all stories are OPEN, no related PRs are open, no related branches exist
+7. **Clear epic-state memory**: Delete all entries in the `epic-state` memory namespace for this epic and its stories (keys: `epic-<N>`, `story-<N>` for each story). Use `mcp__moflo__memory_list` with namespace `epic-state` to find entries, then `mcp__moflo__memory_delete` for each.
+8. **Verify clean state**: Confirm all stories are OPEN, no related PRs are open, no related branches exist, and epic-state memory is empty
 
 ## Output
 

package/.claude/skills/spell-builder/SKILL.md

@@ -136,6 +136,65 @@ Permissions for step "analyze-logs":
 - `{credentials.NAME}` — references a credential (resolved at runtime)
 - `{stepId.outputKey}` — references output from a previous step
 
+#### REQUIRED: Preflight checks with human-readable hints
+
+When a step depends on runtime state the user controls (clean git tree, logged-in CLI, reachable host, etc.), declare a `preflight:` block so the spell fails fast with a helpful message BEFORE any side effects occur.
+
+**Every preflight MUST include a `hint:` field.** The hint is what the end user will see when the check fails. Without it they get raw shell output (`command "git diff --quiet" exited with 1, expected 0`), which looks like a bug in the spell engine.
+
+Good hints:
+- Speak in plain English (no command names, exit codes, or tool jargon).
+- State the problem AND the fix in one or two sentences.
+- Assume a non-technical reader.
+
+```yaml
+steps:
+  - id: create-branch
+    type: bash
+    preflight:
+      - name: "working tree clean (tracked changes)"
+        command: "git diff --quiet"
+        hint: "You have uncommitted changes to tracked files. Commit them or stash them (git stash) before running this spell."
+      - name: "gh cli authenticated"
+        command: "gh auth status"
+        hint: "The GitHub CLI isn't signed in. Run: gh auth login"
+    config:
+      command: "git checkout -b feature/new"
+```
+
+Bad hint (don't do this):
+```yaml
+hint: "git diff --quiet failed with exit code 1"   # leaks command name + exit code
+hint: "Precondition violated"                       # tells user nothing actionable
+```
+
+Preflights with no `hint` still work but produce unfriendly default output — flag this to the user as a quality issue before saving the spell.
+
+##### Fatal vs warning severity
+
+By default every preflight is `severity: fatal` — if it fails, the spell aborts. Some preflights are better expressed as `severity: warning`: the user gets to choose how to handle the problem, and the spell continues if they pick a resolution.
+
+Use `warning` ONLY when:
+- The underlying problem has a safe, one-step fix the user might reasonably want to apply.
+- Proceeding is viable either way — the step itself is robust to the condition.
+
+Warning preflights MUST declare `resolutions:` — a list of options the user can pick from. Each resolution has a `label` and an optional `command` to run before continuing. If `command` is omitted, picking the resolution just proceeds (useful for "I'll handle it myself").
+
+```yaml
+preflight:
+  - name: "working tree clean (tracked changes)"
+    command: "git diff --quiet"
+    severity: "warning"
+    hint: "You have uncommitted changes. If you want them carried onto the new branch, pick 'Stash and carry over'."
+    resolutions:
+      - label: "Stash changes and carry them onto the new branch"
+        command: "git stash push --include-untracked --message 'pre-spell autostash'"
+      - label: "Commit changes to the current branch first, then continue"
+        command: "git commit -am 'wip: pre-spell snapshot'"
+```
+
+In non-interactive contexts (CI, daemons, scheduled spells) warnings automatically behave like fatals, because there is no one to prompt. Don't use `warning` as a way to silently ignore a problem — if ignoring it is always safe, the check shouldn't be there.
+
 ### Step 4: Generate the Spell YAML
 
 Assemble the definition into YAML format following this structure:
@@ -407,6 +466,13 @@ arguments:
 steps:
   - id: scan-deps
     type: bash
+    preflight:
+      - name: "npm available"
+        command: "npm --version"
+        hint: "npm isn't installed or isn't on your PATH. Install Node.js from https://nodejs.org and try again."
+      - name: "target directory exists"
+        command: "test -d \"{args.target}\""
+        hint: "The directory you passed as --target doesn't exist. Check the path and try again."
     config:
       command: "npm audit --json"
       cwd: "{args.target}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.56-rc.9",
+  "version": "4.8.57",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -111,7 +111,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.19.37",
     "eslint": "^8.0.0",
-    "moflo": "^4.8.56-rc.8",
+    "moflo": "^4.8.56",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

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

@@ -12,10 +12,12 @@
  *   flo epic reset <epic-number>             Clear epic memory state
  */
 import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isEpicIssue, fetchEpicIssue, extractStories, enrichStoryNames, resolveExecutionOrder, } from '../epic/index.js';
-import { runEpicSpell } from '../epic/runner-adapter.js';
+import { runEpicSpell, } from '../epic/runner-adapter.js';
+import { select } from '../prompt.js';
 // ============================================================================
 // Spell Template Loader
 // ============================================================================
@@ -80,8 +82,34 @@ async function runEpic(source, strategy, dryRun) {
     catch {
         // No prior state — fresh run
     }
+    // 3b. Reconcile memory with branch state — if the branch doesn't exist
+    //     or has no commits ahead of main, memory is stale (e.g. after a reset)
     if (completedStories.size > 0) {
-        console.log(`[epic] Resuming: ${completedStories.size} stories already completed`);
+        const slug = issue.title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .substring(0, 40);
+        const epicBranch = `epic/${issueNumber}-${slug}`;
+        let branchHasCommits = false;
+        try {
+            // Check if the epic branch exists (local or remote) and has commits ahead of main
+            const revCheck = execSync(`git rev-parse --verify refs/heads/${epicBranch} 2>/dev/null || git rev-parse --verify refs/remotes/origin/${epicBranch} 2>/dev/null`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (revCheck) {
+                const aheadCount = execSync(`git rev-list --count main..${revCheck}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+                branchHasCommits = parseInt(aheadCount, 10) > 0;
+            }
+        }
+        catch {
+            // Branch doesn't exist — memory is stale
+        }
+        if (branchHasCommits) {
+            console.log(`[epic] Resuming: ${completedStories.size} stories already completed (branch verified)`);
+        }
+        else {
+            console.log(`[epic] Memory shows ${completedStories.size} completed stories, but epic branch is missing or empty — starting fresh`);
+            completedStories = new Set();
+        }
     }
     // 4. Build slug for branch name
     const slug = issue.title
@@ -156,6 +184,7 @@ async function runEpic(source, strategy, dryRun) {
                     console.log(`[epic]   └─ ${stepResult.error}`);
                 }
             },
+            onPreflightWarnings: isInteractive() ? resolvePreflightWarningsInteractively : undefined,
         });
         if (result.success) {
             console.log(`\n[epic] Epic #${issueNumber} completed successfully`);
@@ -168,8 +197,16 @@ async function runEpic(source, strategy, dryRun) {
             return { success: true, message: 'Epic completed', data: result };
         }
         else {
+            const firstErr = result.errors[0];
+            const errCode = firstErr?.code;
+            // Preflight failures are user environment problems, not epic bugs.
+            // Show only the friendly prerequisite message, nothing else.
+            if (errCode === 'PREFLIGHT_FAILED' && typeof firstErr?.message === 'string') {
+                console.log(`\n${firstErr.message}`);
+                console.log('\nThe epic was not started. Fix the item(s) above and try again.');
+                return { success: false, message: firstErr.message, data: result };
+            }
             console.log(`\n[epic] Epic #${issueNumber} failed`);
-            // Print step-level results for visibility
             if (result.steps && result.steps.length > 0) {
                 for (const step of result.steps) {
                     const icon = step.status === 'succeeded' ? '✓' : step.status === 'skipped' ? '○' : '✗';
@@ -180,7 +217,6 @@ async function runEpic(source, strategy, dryRun) {
                     }
                 }
             }
-            // Print spell-level errors with full detail
             for (const err of result.errors) {
                 const prefix = err.stepId
                     ? `  [${err.stepId}]`
@@ -193,8 +229,6 @@ async function runEpic(source, strategy, dryRun) {
                     }
                 }
             }
-            // Build actionable error message from first failure
-            const firstErr = result.errors[0];
             const rawMsg = firstErr?.message ?? 'Unknown error';
             const summary = buildFailureSummary(rawMsg, {
                 stepId: firstErr?.stepId,
@@ -244,16 +278,68 @@ async function resetEpic(epicNumber) {
         return { success: false, message: 'Usage: flo epic reset <epic-number>' };
     }
     console.log(`[epic] Clearing state for epic #${epicNumber}...`);
+    // 1. Find all story keys for this epic from memory
+    let storyKeys = [];
     try {
-        await runEpicSpell(`name: epic-reset\nsteps:\n  - id: clear-state\n    type: memory\n    config:\n      action: write\n      namespace: epic-state\n      key: "epic-${epicNumber}"\n      value: null`, { args: {} });
-        console.log(`[epic] State cleared for epic #${epicNumber}`);
+        const searchResult = await runEpicSpell(`name: epic-reset-search\nsteps:\n  - id: find-stories\n    type: memory\n    config:\n      action: search\n      namespace: epic-state\n      query: "epic ${epicNumber} story completed"`, { args: {} });
+        if (searchResult.success && searchResult.outputs['find-stories']) {
+            const data = searchResult.outputs['find-stories'];
+            if (data.results) {
+                storyKeys = data.results.map(r => r.key).filter(k => k.startsWith('story-'));
+            }
+        }
     }
     catch {
-        console.log(`[epic] Could not clear epic state.`);
+        // Couldn't search — just clear the epic key below
     }
+    // 2. Clear epic key + all story keys
+    const keysToDelete = [`epic-${epicNumber}`, ...storyKeys];
+    let cleared = 0;
+    for (const key of keysToDelete) {
+        try {
+            await runEpicSpell(`name: epic-reset-delete\nsteps:\n  - id: delete-key\n    type: memory\n    config:\n      action: write\n      namespace: epic-state\n      key: "${key}"\n      value: null`, { args: {} });
+            cleared++;
+        }
+        catch {
+            // Key may not exist — safe to ignore
+        }
+    }
+    console.log(`[epic] Cleared ${cleared} memory entries for epic #${epicNumber}`);
     return { success: true };
 }
 // ============================================================================
+// Preflight warning interactive resolver
+// ============================================================================
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY) && process.env.CI !== 'true';
+}
+async function resolvePreflightWarningsInteractively(warnings) {
+    console.log('\nBefore this spell starts, some things need your attention:\n');
+    const decisions = [];
+    for (let i = 0; i < warnings.length; i++) {
+        const w = warnings[i];
+        const choices = [
+            ...w.resolutions.map((r, idx) => ({
+                label: r.label,
+                value: { action: 'resolve', resolutionIndex: idx },
+            })),
+            { label: "Continue anyway (I'll handle it)", value: { action: 'continue' } },
+            { label: 'Abort the spell', value: { action: 'abort' } },
+        ];
+        const decision = await select({
+            message: `${i + 1}. ${w.reason}`,
+            options: choices,
+        });
+        decisions.push(decision);
+        if (decision.action === 'abort') {
+            while (decisions.length < warnings.length)
+                decisions.push({ action: 'abort' });
+            break;
+        }
+    }
+    return decisions;
+}
+// ============================================================================
 // Error remediation hints
 // ============================================================================
 const REMEDIATION_PATTERNS = [

package/src/modules/cli/dist/src/epic/runner-adapter.js

@@ -7,10 +7,24 @@
  * Story #197: Thin adapter for running spell YAML from epic command.
  * Story #229: Uses shared engine loader instead of inline dynamic import.
  */
-import { loadSpellEngine } from '../services/engine-loader.js';
+import * as readline from 'node:readline';
+import { loadSpellEngine, } from '../services/engine-loader.js';
 import { createDashboardMemoryAccessor } from '../services/daemon-dashboard.js';
 /** Cached memory accessor — created once per process. */
 let memoryAccessor = null;
+/** Prompt the user to accept or decline spell permissions. */
+async function promptAcceptPermissions() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise(resolve => {
+            rl.question('\n[epic] Accept these permissions? (y/N) ', resolve);
+        });
+        return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * Run a spell YAML string via the spell engine.
  *
@@ -31,6 +45,34 @@ export async function runEpicSpell(yamlContent, options = {}) {
             console.warn('[epic] ⚠ Spell executions will NOT appear in the dashboard');
         }
     }
-    return engine.runSpellFromContent(yamlContent, undefined, { ...options, ...(memoryAccessor ? { memory: memoryAccessor } : {}) });
+    const runOpts = { ...options, projectRoot: process.cwd(), ...(memoryAccessor ? { memory: memoryAccessor } : {}) };
+    const result = await engine.runSpellFromContent(yamlContent, undefined, runOpts);
+    // Auto-accept permissions on first run: the spell runner already printed
+    // the full risk analysis to the console. The user initiated the epic
+    // command, so we accept on their behalf and retry immediately.
+    const hasAcceptanceError = !result.success &&
+        result.errors.some(e => e.code === 'ACCEPTANCE_REQUIRED');
+    if (hasAcceptanceError) {
+        const accepted = await promptAcceptPermissions();
+        if (!accepted) {
+            return result;
+        }
+        // Use the already-loaded engine module (dynamic import) for spells internals.
+        // Static cross-package imports break when installed as a dependency because
+        // the relative paths from dist/ don't match the source layout.
+        const spells = engine;
+        const { parseSpell, StepCommandRegistry, builtinCommands, analyzeSpellPermissions, recordAcceptance } = spells;
+        const projectRoot = process.cwd();
+        const parsed = parseSpell(yamlContent);
+        const stepRegistry = new StepCommandRegistry();
+        for (const cmd of builtinCommands) {
+            stepRegistry.register(cmd, 'built-in');
+        }
+        const report = analyzeSpellPermissions(parsed.definition, stepRegistry);
+        await recordAcceptance(projectRoot, parsed.definition.name, report.permissionHash);
+        console.log(`[epic] Permissions accepted for "${parsed.definition.name}" — retrying...\n`);
+        return engine.runSpellFromContent(yamlContent, undefined, runOpts);
+    }
+    return result;
 }
 //# sourceMappingURL=runner-adapter.js.map

package/src/modules/cli/dist/src/epic/spells/auto-merge.yaml

@@ -33,14 +33,6 @@ arguments:
 mofloLevel: hooks
 
 steps:
-  # Step 0: Pre-flight — fail fast if worktree is dirty or has unmerged files
-  - id: preflight-check
-    type: bash
-    config:
-      command: "if [ -n \"$(git diff --name-only --diff-filter=U 2>/dev/null)\" ]; then echo 'ERROR: Unmerged files detected. Resolve conflicts before running epic.' >&2; git diff --name-only --diff-filter=U 2>/dev/null >&2; exit 1; fi && if [ -n \"$(git -c core.autocrlf=false -c core.safecrlf=false status --porcelain 2>/dev/null)\" ]; then echo 'ERROR: Working tree is dirty. Commit, stash, or discard changes before running epic.' >&2; git -c core.autocrlf=false -c core.safecrlf=false status --short 2>/dev/null >&2; exit 1; fi"
-      timeout: 120000
-      failOnError: true
-
   # Step 1: Initialize epic state in memory (enables resume)
   - id: init-state
     type: memory
@@ -62,8 +54,39 @@ steps:
     output: story_results
     steps:
       # 1: Checkout and pull latest base branch
+      # Preflights run once BEFORE any step (not per iteration) — fail fast
+      # on dirty tree, missing auth, or unreachable remote.
       - id: checkout-base
         type: bash
+        preflight:
+          - name: "no unmerged files"
+            command: "git diff --name-only --diff-filter=U"
+            expectExitCode: 0
+            hint: "You have unresolved merge conflicts. Resolve them and commit before running this spell."
+          - name: "working tree clean (tracked changes)"
+            command: "git diff --quiet"
+            severity: "warning"
+            hint: "You have uncommitted changes to tracked files. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+            resolutions:
+              - label: "Stash changes and carry them onto the epic branch"
+                command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+              - label: "Commit changes to the current branch first, then continue"
+                command: "git commit -am 'wip: pre-epic snapshot'"
+          - name: "working tree clean (staged changes)"
+            command: "git diff --cached --quiet"
+            severity: "warning"
+            hint: "You have staged changes that aren't committed. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+            resolutions:
+              - label: "Stash staged changes and carry them onto the epic branch"
+                command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+              - label: "Commit staged changes to the current branch first, then continue"
+                command: "git commit -m 'wip: pre-epic snapshot'"
+          - name: "gh cli authenticated"
+            command: "gh auth status"
+            hint: "The GitHub CLI isn't signed in. Run: gh auth login"
+          - name: "origin remote configured"
+            command: "git remote get-url origin"
+            hint: "This repo has no 'origin' remote. Set one with: git remote add origin <url>"
         config:
           command: "git stash --include-untracked -q 2>/dev/null; git checkout {args.base_branch} && git pull origin {args.base_branch}; git stash pop -q 2>/dev/null || true"
           failOnError: true