moflo 4.8.56-rc.8 → 4.8.56

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/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/package.json

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

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

@@ -12,6 +12,7 @@
  *   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';
@@ -80,8 +81,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
@@ -244,13 +271,33 @@ 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 };
 }
 // ============================================================================

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 * 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,22 @@ 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
+          - name: "working tree clean (tracked changes)"
+            command: "git diff --quiet"
+          - name: "working tree clean (staged changes)"
+            command: "git diff --cached --quiet"
+          - name: "gh cli authenticated"
+            command: "gh auth status"
+          - name: "origin remote configured"
+            command: "git remote get-url origin"
         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

package/src/modules/cli/dist/src/epic/spells/single-branch.yaml

@@ -38,14 +38,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
@@ -59,9 +51,20 @@ steps:
         stories: "{args.stories}"
         branch: "epic/{args.epic_number}-{args.epic_slug}"
 
-  # Step 1: Create epic branch from base
+  # Step 2: Create epic branch from base
+  # Preflights run BEFORE any step — fail fast on dirty tree or auth issues
   - id: create-branch
     type: bash
+    preflight:
+      - name: "no unmerged files"
+        command: "git diff --name-only --diff-filter=U"
+        expectExitCode: 0
+      - name: "working tree clean (tracked changes)"
+        command: "git diff --quiet"
+      - name: "working tree clean (staged changes)"
+        command: "git diff --cached --quiet"
+      - name: "gh cli authenticated"
+        command: "gh auth status"
     config:
       command: "git stash --include-untracked -q 2>/dev/null; git checkout {args.base_branch} && git pull origin {args.base_branch} && (git show-ref --verify --quiet refs/heads/epic/{args.epic_number}-{args.epic_slug} && git checkout epic/{args.epic_number}-{args.epic_slug} || git checkout -b epic/{args.epic_number}-{args.epic_slug}); git stash pop -q 2>/dev/null || true"
       timeout: 120000
@@ -104,8 +107,12 @@ steps:
             epic: "{args.epic_number}"
 
   # Step 3: Push epic branch
+  # Preflight: verify origin remote exists so push won't fail mid-way
   - id: push-branch
     type: bash
+    preflight:
+      - name: "origin remote configured"
+        command: "git remote get-url origin"
     config:
       command: "git push -u origin epic/{args.epic_number}-{args.epic_slug}"
       timeout: 120000

package/src/modules/cli/dist/src/mcp-tools/spell-tools.js

@@ -607,5 +607,49 @@ export const spellTools = [
             return { action, error: `Unknown action: ${action}. Use 'list' or 'info'.` };
         },
     },
+    // --------------------------------------------------------------------------
+    // spell_accept — Accept a spell's permissions after reviewing risk analysis
+    // --------------------------------------------------------------------------
+    {
+        name: 'spell_accept',
+        description: 'Accept a spell\'s permissions after reviewing the risk analysis. Required before first execution.',
+        category: 'spell',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Spell name (as shown in the risk analysis)' },
+            },
+            required: ['name'],
+        },
+        handler: async (input) => {
+            const spellName = input.name;
+            // Dynamically import to avoid circular deps with the spell engine
+            const { recordAcceptance } = await import('../../../../modules/spells/src/core/permission-acceptance.js');
+            const { analyzeSpellPermissions } = await import('../../../../modules/spells/src/core/permission-disclosure.js');
+            const { StepCommandRegistry } = await import('../../../../modules/spells/src/core/step-command-registry.js');
+            const { builtinCommands } = await import('../../../../modules/spells/src/commands/index.js');
+            const projectRoot = findProjectRoot();
+            // Resolve the spell definition
+            const registry = await getRegistry();
+            const loaded = registry.resolve(spellName);
+            if (!loaded) {
+                return { error: `Spell not found in grimoire: ${spellName}` };
+            }
+            // Build a step command registry for permission analysis
+            const stepRegistry = new StepCommandRegistry();
+            for (const cmd of builtinCommands) {
+                stepRegistry.register(cmd, 'built-in');
+            }
+            const report = analyzeSpellPermissions(loaded.definition, stepRegistry);
+            await recordAcceptance(projectRoot, loaded.definition.name, report.permissionHash);
+            return {
+                accepted: true,
+                spell: loaded.definition.name,
+                permissionHash: report.permissionHash,
+                overallRisk: report.overallRisk,
+                message: `Permissions accepted for "${loaded.definition.name}". You can now cast this spell.`,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=spell-tools.js.map

package/src/modules/cli/dist/src/mcp-tools/tool-names.js

@@ -10,6 +10,7 @@ export const TOOL_SPELL_LIST = 'spell_list';
 export const TOOL_SPELL_STATUS = 'spell_status';
 export const TOOL_SPELL_CANCEL = 'spell_cancel';
 export const TOOL_SPELL_TEMPLATE = 'spell_template';
+export const TOOL_SPELL_ACCEPT = 'spell_accept';
 // Memory tools
 export const TOOL_MEMORY_STORE = 'memory_store';
 export const TOOL_MEMORY_RETRIEVE = 'memory_retrieve';

package/src/modules/cli/dist/src/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.8.56-rc.8';
+export const VERSION = '4.8.56';
 //# sourceMappingURL=version.js.map

package/src/modules/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.8.56-rc.8",
+  "version": "4.8.56",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "preversion": "echo 'ERROR: Run npm version from the repo root, not from src/modules/cli/' && exit 1",
-    "build": "tsc && node -e \"const{cpSync}=require('fs');cpSync('src/epic/workflows','dist/src/epic/workflows',{recursive:true})\"",
+    "build": "tsc && node -e \"const{cpSync}=require('fs');cpSync('src/epic/spells','dist/src/epic/spells',{recursive:true})\"",
     "test": "vitest run",
     "test:plugin-store": "npx tsx src/plugins/tests/standalone-test.ts",
     "test:pattern-store": "npx tsx src/transfer/store/tests/standalone-test.ts",

package/src/modules/plugins/dist/index.js

@@ -102,7 +102,6 @@ export { Security, validateString, validateNumber, validateBoolean, validateArra
 // ============================================================================
 export const VERSION = '3.0.0-alpha.1';
 export const SDK_VERSION = '1.0.0';
-export const MODULE_ID = '@claude-flow/plugins';
 // ============================================================================
 // Quick Start Utilities
 // ============================================================================

package/src/modules/shared/dist/utils/platform.js

@@ -1,8 +1,6 @@
 /**
  * Cross-platform utilities for shell commands and path handling.
  */
-/** Date of the cross-platform audit */
-export const PLATFORM_AUDIT_DATE = '2026-04-01';
 /** True when running on Windows */
 export const IS_WINDOWS = process.platform === 'win32';
 /** Platform-appropriate null device for stderr/stdout redirection */

package/src/modules/spells/dist/commands/bash-command.js

@@ -134,7 +134,7 @@ export const bashCommand = {
             };
         }
         const elapsed = () => `${((Date.now() - start) / 1000).toFixed(1)}s`;
-        const cmdPreview = command.length > 80 ? command.slice(0, 77) + '...' : command;
+        const cmdPreview = redactSensitiveFlags(command.length > 80 ? command.slice(0, 77) + '...' : command);
         // Resolve shell: prefer Git Bash on Windows to avoid WSL bash hanging.
         const resolvedShell = platform() === 'win32' ? resolveGitBash() : 'bash';
         // ── OS sandbox wrapping (#410 macOS, #411 Linux) ────────────────────
@@ -347,7 +347,7 @@ function resolveGitBash() {
  * Interactive Claude invocations are left untouched.
  */
 const CLAUDE_HEADLESS_RE = /\bclaude\b[^|;&]*\s-p\s/;
-const EXISTING_PERM_FLAGS_RE = /\s*--dangerously-skip-permissions\b/g;
+const EXISTING_PERM_FLAGS_RE = /\s*(?:--dangerously-skip-permissions|--permission-mode\s+\S+)\b/g;
 const EXISTING_ALLOWED_TOOLS_RE = /\s*--allowedTools\s+[^\s]+/g;
 function applyClaudePermissions(command, explicitLevel, capabilities) {
     if (!CLAUDE_HEADLESS_RE.test(command))
@@ -364,6 +364,11 @@ function applyClaudePermissions(command, explicitLevel, capabilities) {
     rewritten = rewritten.replace(/ {2,}/g, ' ');
     return rewritten;
 }
+// ── Log redaction — strip alarming flags from heartbeat output ───────────
+const REDACT_FLAGS_RE = /\s*(?:--dangerously-skip-permissions|--permission-mode\s+\S+)\b/g;
+function redactSensitiveFlags(cmd) {
+    return cmd.replace(REDACT_FLAGS_RE, '').replace(/ {2,}/g, ' ');
+}
 // ── Best-effort path extraction for scope enforcement ────────────────────
 /**
  * Extract absolute paths from a shell command string.

package/src/modules/spells/dist/commands/github-command.js

@@ -37,6 +37,41 @@ const githubPrerequisites = [
     },
 ];
 // ============================================================================
+// Preflights — runtime state checks
+// ============================================================================
+/** Confirm an issue/PR number referenced in config actually exists. */
+const githubPreflights = [
+    {
+        name: 'issue-exists',
+        check: async (config) => {
+            if (typeof config.issue !== 'number')
+                return { passed: true };
+            // Skip for create-type actions that don't require the issue to exist.
+            if (config.action === 'issue-edit' || config.action === 'issue-fetch' || config.action === 'comment' || config.action === 'label') {
+                const result = await execAsync(`gh issue view ${config.issue} --json number`, 5000);
+                if (result.exitCode === 0)
+                    return { passed: true };
+                return { passed: false, reason: `issue #${config.issue} not found or not accessible` };
+            }
+            return { passed: true };
+        },
+    },
+    {
+        name: 'pr-exists',
+        check: async (config) => {
+            if (typeof config.pr !== 'number')
+                return { passed: true };
+            if (config.action === 'pr-merge' || config.action === 'pr-find') {
+                const result = await execAsync(`gh pr view ${config.pr} --json number`, 5000);
+                if (result.exitCode === 0)
+                    return { passed: true };
+                return { passed: false, reason: `PR #${config.pr} not found or not accessible` };
+            }
+            return { passed: true };
+        },
+    },
+];
+// ============================================================================
 // GitHub Step Command (thin wrapper delegating to github-cli tool)
 // ============================================================================
 export const githubCommand = {
@@ -45,6 +80,7 @@ export const githubCommand = {
     capabilities: [{ type: 'shell' }, { type: 'net' }],
     defaultMofloLevel: 'none',
     prerequisites: githubPrerequisites,
+    preflight: githubPreflights,
     configSchema: {
         type: 'object',
         properties: {

package/src/modules/spells/dist/core/permission-disclosure.js

@@ -16,37 +16,34 @@
 import { resolvePermissions, } from './permission-resolver.js';
 import { checkCapabilities } from './capability-validator.js';
 import { createHash } from 'node:crypto';
-// ============================================================================
-// Destructive Capability Classification
-// ============================================================================
 /**
- * Capabilities classified as destructive — can permanently modify or delete
+ * Capabilities classified as higher-risk — can permanently modify or delete
  * data, spawn processes, or access credentials. Users must be made aware.
  */
-const DESTRUCTIVE_CAPABILITIES = new Set([
+const HIGHER_RISK_CAPABILITIES = new Set([
     'shell',
     'fs:write',
     'browser:evaluate',
     'credentials',
 ]);
 /**
- * Capabilities classified as sensitive — can read private data or spawn
- * autonomous processes. Not destructive, but worth calling out.
+ * Capabilities classified as moderate-risk — can read private data or spawn
+ * autonomous processes. Worth calling out but not directly destructive.
  */
-const SENSITIVE_CAPABILITIES = new Set([
+const MODERATE_RISK_CAPABILITIES = new Set([
     'agent',
     'net',
     'browser',
 ]);
 /** Human-readable risk explanations for each capability. */
 const RISK_EXPLANATIONS = {
-    'shell': 'Can execute arbitrary shell commands (rm, git push, etc.)',
-    'fs:write': 'Can create, overwrite, or delete files on disk',
-    'browser:evaluate': 'Can execute JavaScript in a browser context',
-    'credentials': 'Can access stored secrets and API keys',
-    'agent': 'Can spawn autonomous Claude sub-agents',
-    'net': 'Can make network requests to external services',
-    'browser': 'Can launch and control browser sessions',
+    'shell': 'Runs shell commands on your machine',
+    'fs:write': 'Creates, overwrites, or deletes files',
+    'browser:evaluate': 'Executes JavaScript in a browser context',
+    'credentials': 'Accesses stored secrets and API keys',
+    'agent': 'Spawns autonomous AI sub-agents',
+    'net': 'Makes network requests to external services',
+    'browser': 'Launches and controls browser sessions',
 };
 // ============================================================================
 // Analysis Functions
@@ -104,18 +101,18 @@ export function analyzeSpellPermissions(definition, registry) {
 function classifyCapabilities(caps) {
     const warnings = [];
     for (const cap of caps) {
-        if (DESTRUCTIVE_CAPABILITIES.has(cap.type)) {
+        if (HIGHER_RISK_CAPABILITIES.has(cap.type)) {
             warnings.push({
                 capability: cap.type,
-                riskLevel: 'destructive',
+                riskLevel: 'higher',
                 explanation: RISK_EXPLANATIONS[cap.type] ?? `Has ${cap.type} access`,
                 scope: cap.scope,
             });
         }
-        else if (SENSITIVE_CAPABILITIES.has(cap.type)) {
+        else if (MODERATE_RISK_CAPABILITIES.has(cap.type)) {
             warnings.push({
                 capability: cap.type,
-                riskLevel: 'sensitive',
+                riskLevel: 'moderate',
                 explanation: RISK_EXPLANATIONS[cap.type] ?? `Has ${cap.type} access`,
                 scope: cap.scope,
             });
@@ -124,11 +121,11 @@ function classifyCapabilities(caps) {
     return warnings;
 }
 function computeRiskLevel(warnings) {
-    if (warnings.some(w => w.riskLevel === 'destructive'))
-        return 'destructive';
-    if (warnings.some(w => w.riskLevel === 'sensitive'))
-        return 'sensitive';
-    return 'safe';
+    if (warnings.some(w => w.riskLevel === 'higher'))
+        return 'higher';
+    if (warnings.some(w => w.riskLevel === 'moderate'))
+        return 'moderate';
+    return 'none';
 }
 // ============================================================================
 // Permission Hash (for acceptance tracking)
@@ -159,18 +156,19 @@ function computePermissionHash(steps) {
 // ============================================================================
 // Formatting — Human-Readable Output
 // ============================================================================
-const RISK_ICONS = {
-    safe: '[SAFE]',
-    sensitive: '[SENSITIVE]',
-    destructive: '[DESTRUCTIVE]',
+const RISK_LABELS = {
+    none: '[No risk]',
+    low: '[Low risk]',
+    moderate: '[Moderate risk]',
+    higher: '[Higher risk]',
 };
 /**
  * Format a single step's permission report for display.
  */
 export function formatStepPermissionReport(report) {
     const lines = [];
-    const icon = RISK_ICONS[report.riskLevel];
-    lines.push(`  ${icon} ${report.stepId} (${report.stepType})`);
+    const label = RISK_LABELS[report.riskLevel];
+    lines.push(`  ${label} ${report.stepId} (${report.stepType})`);
     lines.push(`    Permission level: ${report.permissionLevel}`);
     if (report.resolved.allowedTools) {
         lines.push(`    Allowed tools: ${report.resolved.allowedTools.join(', ')}`);
@@ -179,13 +177,11 @@ export function formatStepPermissionReport(report) {
         lines.push(`    Allowed tools: ALL (autonomous)`);
     }
     if (report.warnings.length > 0) {
-        lines.push('    Warnings:');
         for (const w of report.warnings) {
             const scopeNote = w.scope?.length
                 ? ` (scoped to: ${w.scope.join(', ')})`
                 : '';
-            const marker = w.riskLevel === 'destructive' ? '!!' : '!';
-            lines.push(`      ${marker} ${w.capability}: ${w.explanation}${scopeNote}`);
+            lines.push(`    - ${w.capability}: ${w.explanation}${scopeNote}`);
         }
     }
     return lines.join('\n');
@@ -196,22 +192,19 @@ export function formatStepPermissionReport(report) {
  */
 export function formatSpellPermissionReport(report) {
     const lines = [];
-    lines.push(`Permission Report: ${report.spellName}`);
-    lines.push(`Overall risk: ${RISK_ICONS[report.overallRisk]} ${report.overallRisk}`);
+    lines.push(`--- Risk Analysis: ${report.spellName} ---`);
+    lines.push(`Overall: ${RISK_LABELS[report.overallRisk]}`);
     lines.push(`Permission hash: ${report.permissionHash}`);
     lines.push('');
     for (const step of report.steps) {
         lines.push(formatStepPermissionReport(step));
         lines.push('');
     }
-    if (report.overallRisk === 'destructive') {
-        const destructiveSteps = report.steps.filter(s => s.riskLevel === 'destructive');
-        lines.push('--- DESTRUCTIVE STEPS ---');
-        lines.push(`${destructiveSteps.length} step(s) can make destructive changes:`);
-        for (const s of destructiveSteps) {
-            const caps = s.warnings
-                .filter(w => w.riskLevel === 'destructive')
-                .map(w => w.capability);
+    if (report.overallRisk === 'higher' || report.overallRisk === 'moderate') {
+        const riskySteps = report.steps.filter(s => s.riskLevel === 'higher' || s.riskLevel === 'moderate');
+        lines.push(`--- ${riskySteps.length} step(s) require elevated permissions ---`);
+        for (const s of riskySteps) {
+            const caps = s.warnings.map(w => w.capability);
             lines.push(`  - ${s.stepId}: ${caps.join(', ')}`);
         }
         lines.push('');

package/src/modules/spells/dist/core/permission-resolver.js

@@ -2,13 +2,12 @@
  * Permission Resolver — Least-Privilege Escalation for Spell Steps
  *
  * Determines the minimum Claude Code CLI permission flags needed for a step.
- * Always uses --dangerously-skip-permissions (required for non-interactive -p mode)
- * but varies --allowedTools to enforce least-privilege:
+ * Uses the least-permissive --permission-mode for each level:
  *
- *   readonly   → Read,Glob,Grep                    (analysis only)
- *   standard   → Edit,Write,Read,Glob,Grep         (code changes, no shell)
- *   elevated   → Edit,Write,Bash,Read,Glob,Grep    (shell access for git/npm/etc.)
- *   autonomous → (no --allowedTools restriction)    (explicit opt-in only)
+ *   readonly   → Read,Glob,Grep                    (no permission bypass)
+ *   standard   → Edit,Write,Read,Glob,Grep         (--permission-mode acceptEdits)
+ *   elevated   → Edit,Write,Bash,Read,Glob,Grep    (--permission-mode bypassPermissions)
+ *   autonomous → (no --allowedTools restriction)    (--permission-mode bypassPermissions)
  *
  * Resolution order:
  *   1. Explicit `permissionLevel` on the step definition → use directly
@@ -37,8 +36,17 @@ export function resolvePermissions(explicitLevel, capabilities, additionalTools)
     const level = explicitLevel && isValidPermissionLevel(explicitLevel)
         ? explicitLevel
         : deriveFromCapabilities(capabilities);
-    const args = ['--dangerously-skip-permissions'];
+    const args = [];
+    const needsBypass = level === 'elevated' || level === 'autonomous';
     let allowedTools;
+    // Only bypass permissions when the step actually needs it (shell/autonomous)
+    if (needsBypass) {
+        args.push('--permission-mode', 'bypassPermissions');
+    }
+    else if (level === 'standard') {
+        args.push('--permission-mode', 'acceptEdits');
+    }
+    // readonly: no permission mode needed — Read/Glob/Grep don't require approval
     if (level !== 'autonomous') {
         const baseTools = [...TOOL_SETS[level]];
         if (additionalTools) {
@@ -53,7 +61,7 @@ export function resolvePermissions(explicitLevel, capabilities, additionalTools)
     return {
         level,
         cliArgs: args,
-        skipPermissions: true,
+        skipPermissions: needsBypass,
         allowedTools: allowedTools ? Object.freeze([...allowedTools]) : undefined,
     };
 }
@@ -64,7 +72,7 @@ export function resolvePermissions(explicitLevel, capabilities, additionalTools)
  * @param explicitLevel - Optional explicit `permissionLevel` from step config.
  * @param capabilities  - The step's effective capabilities.
  * @param additionalTools - Extra tools beyond the permission level's defaults.
- * @returns The complete command string (e.g. `claude --dangerously-skip-permissions --allowedTools Edit,Write,Read,Glob,Grep -p "..."`)
+ * @returns The complete command string (e.g. `claude --permission-mode acceptEdits --allowedTools Edit,Write,Read,Glob,Grep -p "..."`)
  */
 export function buildClaudeCommand(prompt, explicitLevel, capabilities, additionalTools) {
     const resolved = resolvePermissions(explicitLevel, capabilities, additionalTools);

package/src/modules/spells/dist/core/preflight-checker.js

@@ -0,0 +1,158 @@
+/**
+ * Preflight Checker
+ *
+ * Runs runtime-state validation BEFORE any step executes. Complements
+ * prerequisite-checker.ts (static capability probes) by validating the
+ * actual state each step depends on (e.g. issue is open, branch is clean).
+ *
+ * Two sources contribute preflights:
+ *   1. Step commands may declare a `preflight` array on their interface —
+ *      these run with the resolved step config + args.
+ *   2. Step definitions may declare a YAML `preflight:` list of shell
+ *      commands — these cover ad-hoc runtime checks for generic steps
+ *      (e.g. a bash step that needs `git diff --quiet` first).
+ *
+ * All preflights for all steps run in parallel before step execution begins.
+ * Any failure aborts the spell with a structured PRECHECK_FAILED error.
+ */
+import { execFile } from 'node:child_process';
+import { interpolateString } from './interpolation.js';
+// ============================================================================
+// Collection
+// ============================================================================
+/**
+ * Collect every preflight that will run for this spell.
+ * Walks every step, pulls both step-command preflights and YAML preflights,
+ * and binds each with the step's own context/config.
+ */
+export function collectPreflights(definition, registry, context) {
+    const out = [];
+    collectFromSteps(definition.steps, registry, context, out, 0);
+    return out;
+}
+function collectFromSteps(steps, registry, context, out, startIndex) {
+    let index = startIndex;
+    for (const step of steps) {
+        const command = registry.get(step.type);
+        // 1. Step-command preflights
+        if (command?.preflight) {
+            for (const check of command.preflight) {
+                out.push(bindCommandPreflight(step, index, check, context));
+            }
+        }
+        // 2. Declarative YAML preflights
+        if (step.preflight) {
+            for (const spec of step.preflight) {
+                out.push(bindYamlPreflight(step, index, spec, context));
+            }
+        }
+        // Recurse into nested steps (loops/conditions)
+        if (step.steps && step.steps.length > 0) {
+            index = collectFromSteps(step.steps, registry, context, out, index + 1);
+        }
+        else {
+            index++;
+        }
+    }
+    return index;
+}
+function bindCommandPreflight(step, stepIndex, check, context) {
+    return {
+        stepId: step.id,
+        stepIndex,
+        name: check.name,
+        run: () => {
+            const ctx = {
+                args: context.args,
+                credentials: context.credentials,
+                stepId: step.id,
+                stepIndex,
+            };
+            return check.check(step.config, ctx);
+        },
+    };
+}
+function bindYamlPreflight(step, stepIndex, spec, context) {
+    return {
+        stepId: step.id,
+        stepIndex,
+        name: spec.name,
+        run: async () => {
+            const command = interpolateSafe(spec.command, context.args);
+            const expected = spec.expectExitCode ?? 0;
+            const timeoutMs = spec.timeoutMs ?? 10_000;
+            const actualExitCode = await runShellExitCode(command, timeoutMs);
+            if (actualExitCode === expected)
+                return { passed: true };
+            return {
+                passed: false,
+                reason: `command "${command}" exited with ${actualExitCode}, expected ${expected}`,
+            };
+        },
+    };
+}
+// ============================================================================
+// Execution
+// ============================================================================
+/** Run all preflights in parallel. Errors are treated as failures. */
+export async function checkPreflights(preflights) {
+    return Promise.all(preflights.map(async (pf) => {
+        try {
+            const result = await pf.run();
+            return {
+                stepId: pf.stepId,
+                name: pf.name,
+                passed: result.passed,
+                reason: result.reason,
+            };
+        }
+        catch (err) {
+            return {
+                stepId: pf.stepId,
+                name: pf.name,
+                passed: false,
+                reason: err.message,
+            };
+        }
+    }));
+}
+/** Format failed preflights into a user-friendly error message. */
+export function formatPreflightErrors(results) {
+    const failed = results.filter(r => !r.passed);
+    if (failed.length === 0)
+        return '';
+    const lines = ['Preflight checks failed:'];
+    for (const f of failed) {
+        lines.push(`  - [${f.stepId}] ${f.name}${f.reason ? `: ${f.reason}` : ''}`);
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Internals
+// ============================================================================
+function interpolateSafe(template, args) {
+    try {
+        const ctx = { args, variables: {} };
+        return interpolateString(template, ctx);
+    }
+    catch {
+        return template;
+    }
+}
+async function runShellExitCode(command, timeoutMs) {
+    return new Promise((resolve) => {
+        const shell = process.platform === 'win32' ? process.env.ComSpec ?? 'cmd.exe' : '/bin/sh';
+        const shellArgs = process.platform === 'win32' ? ['/d', '/s', '/c', command] : ['-c', command];
+        const child = execFile(shell, shellArgs, { timeout: timeoutMs }, (err) => {
+            if (err && typeof err.code === 'number') {
+                resolve(err.code);
+            }
+            else if (err && err.signal) {
+                resolve(124); // timeout-ish
+            }
+        });
+        child.on('exit', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+    });
+}
+//# sourceMappingURL=preflight-checker.js.map

package/src/modules/spells/dist/core/runner.js

@@ -1,11 +1,3 @@
-/**
- * Spell Runner
- *
- * Thin orchestrator that drives a parsed SpellDefinition step by step,
- * delegating step execution, validation, loop iteration, rollback,
- * credential masking, and timeout handling to focused modules.
- */
-export const ENGINE_VERSION = '1.0.0';
 import { ConnectorAccessorImpl } from './connector-accessor.js';
 import { validateSpellDefinition, resolveArguments } from '../schema/validator.js';
 import { compareMofloLevels } from './capability-validator.js';
@@ -17,8 +9,11 @@ import { rollbackSteps } from './rollback-orchestrator.js';
 import { buildCredentialPatterns, addCredentialPattern, collectCredentialNames } from './credential-masker.js';
 import { executeSingleStep } from './step-executor.js';
 import { collectPrerequisites, checkPrerequisites, formatPrerequisiteErrors } from './prerequisite-checker.js';
+import { collectPreflights, checkPreflights, formatPreflightErrors } from './preflight-checker.js';
 import { DENY_ALL_GATEWAY } from './capability-gateway.js';
 import { resolveEffectiveSandbox, formatSandboxLog, DEFAULT_SANDBOX_CONFIG, } from './platform-sandbox.js';
+import { checkAcceptance, recordAcceptance } from './permission-acceptance.js';
+import { analyzeSpellPermissions, formatSpellPermissionReport } from './permission-disclosure.js';
 export class SpellCaster {
     registry;
     credentials;
@@ -63,6 +58,45 @@ export class SpellCaster {
                     details: argErrors,
                 }], definition.name);
         }
+        // ---------------------------------------------------------------
+        // Permission acceptance gate: first-run spells show a risk
+        // analysis and block execution until the user explicitly accepts
+        // via the spell_accept MCP tool.
+        // ---------------------------------------------------------------
+        if (!options.dryRun && !options.skipAcceptanceCheck && options.projectRoot) {
+            const permReport = analyzeSpellPermissions(definition, this.registry);
+            const acceptance = await checkAcceptance(options.projectRoot, definition.name, permReport.permissionHash);
+            if (!acceptance.accepted) {
+                // Auto-accept spells with no real risk — no need to prompt the user
+                if (permReport.overallRisk === 'none' || permReport.overallRisk === 'low') {
+                    await recordAcceptance(options.projectRoot, definition.name, permReport.permissionHash);
+                    console.log(`[spell] Auto-accepted "${definition.name}" (${permReport.overallRisk} risk)`);
+                }
+                else {
+                    const reason = acceptance.reason === 'hash-mismatch'
+                        ? 'Spell permissions have changed since last acceptance'
+                        : 'First run — reviewing spell permissions';
+                    const report = formatSpellPermissionReport(permReport);
+                    console.log(`[spell] ${reason}`);
+                    console.log(`[spell] Running automatic dry-run validation...\n`);
+                    console.log(report);
+                    // Run dry-run validation so the user also sees structural issues
+                    const dryResult = await dryRunValidate(definition, resolvedArgs, defValidation, options, this.registry, (variables, wfId, stepIndex) => this.buildContext(variables, resolvedArgs, wfId, stepIndex, options.signal));
+                    if (!dryResult.valid) {
+                        console.log('\n[spell] Dry-run validation found errors:');
+                        for (const err of [...dryResult.definitionErrors, ...dryResult.argumentErrors]) {
+                            console.log(`  - ${err.message}`);
+                        }
+                    }
+                    // Block — user must explicitly accept
+                    console.log(`\n[spell] To accept these permissions, run: spell_accept({ name: "${definition.name}" })`);
+                    return this.failureResult(spellId, startTime, [{
+                            code: 'ACCEPTANCE_REQUIRED',
+                            message: `${reason}. Review the risk analysis above and accept with spell_accept({ name: "${definition.name}" }).`,
+                        }], definition.name);
+                }
+            }
+        }
         // Pre-flight prerequisite checks (Story #193)
         if (!options.dryRun) {
             const prerequisites = collectPrerequisites(definition, this.registry);
@@ -75,6 +109,21 @@ export class SpellCaster {
                         }], definition.name);
                 }
             }
+            // Preflight runtime-state checks — fail fast before any step runs.
+            const preflights = collectPreflights(definition, this.registry, {
+                args: resolvedArgs,
+                credentials: this.credentials,
+            });
+            if (preflights.length > 0) {
+                const preflightResults = await checkPreflights(preflights);
+                if (preflightResults.some(r => !r.passed)) {
+                    console.log(`[spell] ${formatPreflightErrors(preflightResults)}`);
+                    return this.failureResult(spellId, startTime, [{
+                            code: 'PREFLIGHT_FAILED',
+                            message: formatPreflightErrors(preflightResults),
+                        }], definition.name);
+                }
+            }
         }
         if (options.dryRun) {
             const dryResult = await dryRunValidate(definition, resolvedArgs, defValidation, options, this.registry, (variables, wfId, stepIndex) => this.buildContext(variables, resolvedArgs, wfId, stepIndex, options.signal));

package/src/modules/spells/dist/factory/runner-bridge.js

@@ -29,6 +29,7 @@ export async function bridgeRunSpell(content, sourceFile, args, options = {}) {
             signal: controller.signal,
             memory: options.memory,
             credentials: options.credentials,
+            ...(options.projectRoot ? { projectRoot: options.projectRoot } : {}),
         });
         return result;
     }
@@ -48,6 +49,7 @@ export async function bridgeExecuteSpell(definition, args, options = {}) {
         return await runner.run(definition, args, {
             spellId,
             signal: controller.signal,
+            ...(options.projectRoot ? { projectRoot: options.projectRoot } : {}),
         });
     }
     finally {

package/src/modules/spells/dist/factory/runner-factory.js

@@ -76,7 +76,8 @@ export async function runSpellFromContent(content, sourceFile, options = {}) {
         };
     }
     const runner = createRunner(options);
-    const { args = {}, ...runnerOptions } = options;
+    // Strip factory-only fields; keep RunSpellOptions (extends RunnerOptions) for runner.run()
+    const { args = {}, stepDirs: _s, credentials: _c, memory: _m, connectorRegistry: _cr, ...runnerOptions } = options;
     return runner.run(definition, args, runnerOptions);
 }
 // ============================================================================

package/src/modules/spells/dist/schema/validator.js

@@ -155,6 +155,33 @@ function validateSteps(steps, errors, stepIds, outputVars, options, prefix = 'st
                 message: `invalid permissionLevel: "${step.permissionLevel}". Valid levels: ${VALID_PERMISSION_LEVELS.join(', ')}`,
             });
         }
+        // Validate declarative preflight specs (runtime state checks)
+        if (step.preflight !== undefined) {
+            if (!Array.isArray(step.preflight)) {
+                errors.push({ path: `${path}.preflight`, message: 'preflight must be an array' });
+            }
+            else {
+                step.preflight.forEach((pf, pi) => {
+                    const pfPath = `${path}.preflight[${pi}]`;
+                    if (!pf || typeof pf !== 'object') {
+                        errors.push({ path: pfPath, message: 'preflight entry must be an object' });
+                        return;
+                    }
+                    if (typeof pf.name !== 'string' || pf.name.length === 0) {
+                        errors.push({ path: `${pfPath}.name`, message: 'preflight.name is required' });
+                    }
+                    if (typeof pf.command !== 'string' || pf.command.length === 0) {
+                        errors.push({ path: `${pfPath}.command`, message: 'preflight.command is required' });
+                    }
+                    if (pf.expectExitCode !== undefined && typeof pf.expectExitCode !== 'number') {
+                        errors.push({ path: `${pfPath}.expectExitCode`, message: 'expectExitCode must be a number' });
+                    }
+                    if (pf.timeoutMs !== undefined && (typeof pf.timeoutMs !== 'number' || pf.timeoutMs <= 0)) {
+                        errors.push({ path: `${pfPath}.timeoutMs`, message: 'timeoutMs must be a positive number' });
+                    }
+                });
+            }
+        }
         // Recurse into nested steps (condition/loop/parallel)
         if (step.steps && Array.isArray(step.steps)) {
             validateSteps(step.steps, errors, stepIds, outputVars, options, `${path}.steps`, spellLevel);