moflo 4.12.3 → 4.12.4-rc.10

package/.claude/agents/core/coder.md

@@ -195,36 +195,29 @@ src/
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report implementation status
-mcp__moflo__memory_store {
-    key: "swarm/coder/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "coder",
-    status: "implementing",
-    feature: "user authentication",
-    files: ["auth.service.ts", "auth.controller.ts"],
-    timestamp: Date.now()
-  })
-}
 
+Store decisions that outlive this run, in the namespaces named in your operating
+context above. Prose in `value` — it is what gets embedded, so a JSON blob
+retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share code decisions
 mcp__moflo__memory_store {
-    key: "swarm/shared/implementation",
-  namespace: "coordination",
-  value: JSON.stringify({
-    type: "code",
+  namespace: "patterns",
+  key: "auth-service-shape",
+  value: "Auth is a singleton service behind a factory so the jwt signer can be swapped in tests; endpoints are /auth/login and /auth/logout on the express router.",
+  metadata: {
     patterns: ["singleton", "factory"],
     dependencies: ["express", "jwt"],
-    api_endpoints: ["/auth/login", "/auth/logout"]
-  })
+    apiEndpoints: ["/auth/login", "/auth/logout"]
+  }
 }
 
-// Check dependencies
-mcp__moflo__memory_retrieve {
-    key: "swarm/shared/dependencies",
-  namespace: "coordination"
+// Look up what an earlier agent established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service dependencies",
+  namespace: "patterns"
 }
 ```
 
@@ -232,14 +225,13 @@ mcp__moflo__memory_retrieve {
 ```javascript
 // Track implementation metrics
 mcp__moflo__performance_benchmark {
-  type: "code",
+  suite: "memory",
   iterations: 10
 }
 
-// Analyze bottlenecks
+// Read this process's CPU / memory / heap usage
 mcp__moflo__performance_report {
-  component: "api-endpoint",
-  metrics: ["response-time", "memory-usage"]
+  format: "detailed"
 }
 ```
 

package/.claude/agents/core/planner.md

@@ -114,45 +114,67 @@ plan:
 ## MCP Tool Integration
 
 ### Task Orchestration
-```javascript
-// Orchestrate complex tasks
 
-// Share task breakdown
-mcp__moflo__memory_store {
-    key: "swarm/planner/task-breakdown",
-  namespace: "coordination",
-  value: JSON.stringify({
-    main_task: "authentication",
-    subtasks: [
-      {id: "1", task: "Research auth libraries", assignee: "researcher"},
-      {id: "2", task: "Design auth flow", assignee: "architect"},
-      {id: "3", task: "Implement auth service", assignee: "coder"},
-      {id: "4", task: "Write auth tests", assignee: "tester"}
-    ],
-    dependencies: {"3": ["1", "2"], "4": ["3"]}
-  })
+Submit the breakdown to the coordinator. A task ID only exists once the
+coordinator has issued it — storing a breakdown in memory dispatches nothing,
+and polling an ID you invented yourself always comes back empty.
+
+```javascript
+// Submit the whole breakdown in one call. Tasks are load-balanced across
+// available agents; `type` must be one of research | analysis | coding |
+// testing | review | documentation | coordination | consensus | custom.
+mcp__moflo__task_orchestrate {
+  tasks: [
+    { type: "research",      description: "Research auth libraries",  priority: "high" },
+    { type: "analysis",      description: "Design auth flow",         priority: "high" },
+    { type: "coding",        description: "Implement auth service",   priority: "normal" },
+    { type: "testing",       description: "Write auth tests",         priority: "normal" }
+  ]
 }
+// → { success: true, submitted: 4, assigned: 3, queued: 1,
+//     tasks: [ { taskId: "task_...", status: "assigned", ... }, ... ] }
 
-// Monitor task progress
+// Poll an ID the coordinator returned — never one you named yourself.
 mcp__moflo__task_status {
-  taskId: "auth-implementation"
+  taskId: "<taskId from the response above>"
 }
+
+// Or survey everything in flight instead of polling one at a time.
+mcp__moflo__task_list { status: "running,queued" }
 ```
 
+Use `mcp__moflo__task_create` for a single task; it takes the same fields and
+returns the same projection, including the `taskId`.
+
+**Ordering lives on the native Task layer, not here.** `task_create` and
+`task_orchestrate` accept no dependency field — the coordinator load-balances
+what you submit. Express prerequisites with `TaskUpdate({ addBlockedBy: [...] })`
+on the native tasks, per *What → Native Tasks; How → MoFlo orchestration* in
+`.claude/guidance/moflo-claude-swarm-cohesion.md`.
+
 ### Memory Coordination
+
+Live task state belongs to the coordinator — read it with `task_status` /
+`task_list` rather than mirroring it into memory. Store what stays useful after
+this run: a decision and its rationale that a future agent would otherwise have
+to rediscover.
+
 ```javascript
-// Report planning status
+// Prose in `value` — it is what gets embedded, so a JSON blob retrieves badly.
+// Structure goes in `metadata`, which is stored verbatim and not embedded.
 mcp__moflo__memory_store {
-    key: "swarm/planner/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "planner",
-    status: "planning",
-    tasks_planned: 12,
-    estimated_hours: 24,
-    timestamp: Date.now()
-  })
+  namespace: "patterns",
+  key: "auth-rollout-sequencing",
+  value: "Auth work is sequenced research → design → implement → test because the library choice determines the flow design; parallelising design against research produced rework twice.",
+  metadata: {
+    plannedTasks: 12,
+    blockedOn: ["library selection"]
+  }
 }
 ```
 
-Remember: A good plan executed now is better than a perfect plan executed never. Focus on creating actionable, practical plans that drive progress. Always coordinate through memory.
+Use the namespaces named in this agent's operating context above — `patterns`
+for reusable approaches, `learnings` for decisions and gotchas. The `swarm-*`
+namespaces are the coordinator's own persistence; do not write to them.
+
+Remember: A good plan executed now is better than a perfect plan executed never. Focus on creating actionable, practical plans that drive progress. Dispatch through the coordinator; use memory for what outlives the run.

package/.claude/agents/core/researcher.md

@@ -119,46 +119,38 @@ read specific-file.ts
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report research status
-mcp__moflo__memory_store {
-    key: "swarm/researcher/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "researcher",
-    status: "analyzing",
-    focus: "authentication system",
-    files_reviewed: 25,
-    timestamp: Date.now()
-  })
-}
 
+Store findings that stay useful after this run, in the namespaces named in your
+operating context above. Prose in `value` — it is what gets embedded, so a JSON
+blob retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share research findings
 mcp__moflo__memory_store {
-    key: "swarm/shared/research-findings",
-  namespace: "coordination",
-  value: JSON.stringify({
-    patterns_found: ["MVC", "Repository", "Factory"],
+  namespace: "patterns",
+  key: "auth-stack-survey",
+  value: "Auth here is passport + jwt behind an MVC/repository split; the passport version is two majors behind and there is no rate limiting on the login route.",
+  metadata: {
+    patternsFound: ["MVC", "Repository", "Factory"],
     dependencies: ["express", "passport", "jwt"],
-    potential_issues: ["outdated auth library", "missing rate limiting"],
     recommendations: ["upgrade passport", "add rate limiter"]
-  })
+  }
 }
 
-// Check prior research
+// Check prior research. memory_search is semantic — it takes a `query`, not a
+// key glob. Pivot the query on the bare symbol or topic.
 mcp__moflo__memory_search {
-  pattern: "swarm/shared/research-*",
-  namespace: "coordination",
+  query: "authentication stack",
+  namespace: "patterns",
   limit: 10
 }
 ```
 
 ### Analysis Tools
 ```javascript
-// Analyze codebase
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "code_quality"
+// Understand what a change touches and how risky it is
+mcp__moflo__analyze_diff {
+  ref: "main"
 }
 
 // Track research metrics
@@ -172,14 +164,14 @@ mcp__moflo__agent_status {
 - Share findings with planner for task decomposition via memory
 - Provide context to coder for implementation through shared memory
 - Supply tester with edge cases and scenarios in memory
-- Document all findings in coordination memory
+- Document findings in the `patterns` namespace so later agents retrieve them
 
 ## Best Practices
 
 1. **Be Thorough**: Check multiple sources and validate findings
 2. **Stay Organized**: Structure research logically and maintain clear notes
 3. **Think Critically**: Question assumptions and verify claims
-4. **Document Everything**: Store all findings in coordination memory
+4. **Document Everything**: Store findings in `patterns` (or `learnings` for decisions and gotchas)
 5. **Iterate**: Refine research based on new discoveries
 6. **Share Early**: Update memory frequently for real-time coordination
 

package/.claude/agents/core/reviewer.md

@@ -269,51 +269,42 @@ npm run complexity-check
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report review status
-mcp__moflo__memory_store {
-    key: "swarm/reviewer/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "reviewer",
-    status: "reviewing",
-    files_reviewed: 12,
-    issues_found: {critical: 2, major: 5, minor: 8},
-    timestamp: Date.now()
-  })
-}
 
+Store findings that outlive this run, in the namespaces named in your operating
+context above. Prose in `value` — it is what gets embedded, so a JSON blob
+retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
 // Share review findings
 mcp__moflo__memory_store {
-    key: "swarm/shared/review-findings",
-  namespace: "coordination",
-  value: JSON.stringify({
-    security_issues: ["SQL injection in auth.js:45"],
-    performance_issues: ["N+1 queries in user.service.ts"],
-    code_quality: {score: 7.8, coverage: "78%"},
-    action_items: ["Fix SQL injection", "Optimize queries", "Add tests"]
-  })
+  namespace: "patterns",
+  key: "auth-review-findings",
+  value: "Login builds its SQL by string concatenation (auth.js:45) and the user service loads roles per-row inside a loop, so both the injection risk and the N+1 come from the same request path.",
+  metadata: {
+    securityIssues: ["SQL injection in auth.js:45"],
+    performanceIssues: ["N+1 queries in user.service.ts"],
+    actionItems: ["Fix SQL injection", "Batch the role lookup", "Add tests"]
+  }
 }
 
-// Check implementation details
-mcp__moflo__memory_retrieve {
-    key: "swarm/coder/status",
-  namespace: "coordination"
+// Look up what the implementer established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service shape",
+  namespace: "patterns"
 }
 ```
 
 ### Code Analysis
 ```javascript
-// Analyze code quality
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "code_quality"
+// Assess the risk and shape of the change under review
+mcp__moflo__analyze_diff {
+  ref: "main"
 }
 
-// Run security scan
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "security"
+// Scan the diff for prompt-injection and unsafe content
+mcp__moflo__aidefence_scan {
+  input: "<the diff or file under review>"
 }
 ```
 

package/.claude/agents/core/tester.md

@@ -251,35 +251,30 @@ describe('Security', () => {
 ## MCP Tool Integration
 
 ### Memory Coordination
-```javascript
-// Report test status
-mcp__moflo__memory_store {
-    key: "swarm/tester/status",
-  namespace: "coordination",
-  value: JSON.stringify({
-    agent: "tester",
-    status: "running tests",
-    test_suites: ["unit", "integration", "e2e"],
-    timestamp: Date.now()
-  })
-}
 
-// Share test results
+Store what stays useful after this run, in the namespaces named in your
+operating context above. Prose in `value` — it is what gets embedded, so a JSON
+blob retrieves badly; structure goes in `metadata`, stored verbatim.
+
+```javascript
+// Share what the run revealed, not the raw tally
 mcp__moflo__memory_store {
-    key: "swarm/shared/test-results",
-  namespace: "coordination",
-  value: JSON.stringify({
+  namespace: "patterns",
+  key: "auth-suite-flakiness",
+  value: "The two failing auth tests both assert on token expiry against a real clock, so they fail whenever the suite runs slowly under load — freeze the clock rather than widening the tolerance.",
+  metadata: {
     passed: 145,
     failed: 2,
     coverage: "87%",
     failures: ["auth.test.ts:45", "api.test.ts:123"]
-  })
+  }
 }
 
-// Check implementation status
-mcp__moflo__memory_retrieve {
-    key: "swarm/coder/status",
-  namespace: "coordination"
+// Look up what the implementer established. Semantic search first — reach for
+// memory_retrieve only when you already know the exact key.
+mcp__moflo__memory_search {
+  query: "auth service shape",
+  namespace: "patterns"
 }
 ```
 
@@ -287,7 +282,7 @@ mcp__moflo__memory_retrieve {
 ```javascript
 // Run performance benchmarks
 mcp__moflo__performance_benchmark {
-  type: "test",
+  suite: "all",
   iterations: 100
 }
 

package/.claude/guidance/shipped/moflo-claude-swarm-cohesion.md

@@ -94,6 +94,8 @@ npx flo hive-mind init --topology hierarchical-mesh --consensus byzantine
 
 Include task IDs in agent prompts. The `SubagentStart` hook automatically injects the subagent protocol directive — don't repeat it.
 
+Asking for a swarm is asking for agents: an ambient "don't call the Agent tool unless the user requested it" is satisfied by that request. Registering agents via MCP without dispatching them leaves a swarm that passes every gate and does no parallel work.
+
 ```javascript
 TaskUpdate({ taskId: "1", status: "in_progress" })
 Task({
@@ -117,6 +119,8 @@ TaskList()  // Shows what's now unblocked
 TaskUpdate({ taskId: "2", status: "in_progress" })  // Next agent starts
 ```
 
+Close every task you open. moflo's PR gate reads the session transcript on `gh pr create` and prints `N tasks created this session, M still open` (#1374) — an unclosed list reports as unfinished work on the PR. Mark tasks that no longer apply `status: "deleted"`; that closes the loop exactly like `completed`.
+
 ---
 
 ## Coordinator Responsibilities

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

@@ -35,6 +35,7 @@ Source files (`.claude/guidance/*.md`, `docs/**/*.md`, code, tests) flow through
 | `patterns` | Per-file code patterns (services, routes, exports) | `index-patterns.mjs` |
 | `tests` | Test structure and patterns | `index-tests.mjs` |
 | `learnings` | User-stored patterns from work sessions | `mcp__moflo__memory_store` |
+| `verify` | Per-run `/verify` verdict records, keyed `verify:<slug>` | `/verify` skill Step 5 |
 
 Namespaces are independent indexes. Search defaults to `all`; pass `namespace: "guidance"` to target one.
 

package/.claude/guidance/shipped/moflo-sdd.md

@@ -27,16 +27,31 @@ Specs and plans persist as Markdown, one directory per unit of work, under the c
 <specs_dir>/<slug>/plan.md   # the "steps" + how each criterion is verified
 ```
 
-They are indexed into memory on session start, so `mcp__moflo__memory_search` surfaces prior specs across sessions. **Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
+**Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
 
-**Where they live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init` — specs stay local and do not bloat source control, but they also do **not** appear in PRs. To make specs reviewable, point `sdd.specs_dir` at a **tracked** path and commit them:
+### Specs are NOT indexed into memory
+
+Earlier versions indexed `spec.md` / `plan.md` into the `guidance` namespace. They no longer are, and the specs directory is excluded from the guidance walk even when it sits inside a `guidance.directories` entry.
+
+A spec is pre-implementation intent for **one** unit of work, not a project rule. Once implemented it is stale-by-construction, and specs accumulate without bound — so a superseded approach kept surfacing at high similarity alongside real guidance, and the namespace degraded as the project aged. Nothing was gained in exchange: the active spec's path is already known (the `flo sdd` CLI just returned it), so **read it from disk** rather than searching for it.
+
+| To… | Use |
+|---|---|
+| Read the spec/plan you are working on | `Read` the path `flo sdd` returned |
+| Find prior specs across sessions | `flo sdd list` / `flo sdd status <slug>` |
+| Recall what an implementation actually taught you | `memory_search` namespace `learnings` |
+| Recall a past verify verdict | `memory_search` namespace `verify` |
+
+Existing spec rows are removed by the `purge-spec-chunks` migration on the next session start.
+
+**Where specs live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init`. To make specs reviewable in the PR, point `sdd.specs_dir` at a **tracked** path and commit them:
 
 | `sdd.specs_dir` | Committed? | Use when |
 |-----------------|------------|----------|
-| `.moflo/specs` (default) | No (gitignored) | You want the SDD workflow but not spec artifacts in history |
-| `docs/specs`, `.specs`, … (tracked) | Yes | You want specs reviewed in the PR alongside the code |
+| `.moflo/specs` (default) | No (gitignored) | Specs are scratch — the PR body carries the acceptance criteria. Best at high spec volume. |
+| `docs/specs`, `.specs`, … (tracked) | Yes | You want the spec diffed and reviewed alongside the code |
 
-Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it. If the path sits inside a `guidance.directories` entry, specs are indexed once (as guidance), not twice.
+Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it — the CLI to write specs there, the indexer to exclude them.
 
 Each artifact carries a `status` of `draft` or `reviewed` in its frontmatter. The constitution layer (`CLAUDE.md` + `.claude/guidance/`) is referenced by every stage — never restate its invariants inside a spec.
 
@@ -64,7 +79,7 @@ The two review checkpoints are the point: **a spec must be reviewed before its p
 When enforced, `gh pr create` is blocked until the change has been verified end-to-end since the last code edit.
 
 - **On by default (#1294).** Enforced for every `/flo` run; disable per-project with `gates.verify_before_done: false` or per-run with `--no-verify`. On upgrade, consumers with no `verify_before_done` key start enforcing; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
-- **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: learnings, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
+- **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: verify, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
 - **A source edit invalidates a prior verification** — re-run `/verify` after editing. `/ward` and `/quicken` are targeted audits, not the completion gate.
 
 ---

package/.claude/guidance/shipped/moflo-spell-engine.md

@@ -1,6 +1,6 @@
 # Spell Engine — Definition Format & Step Types
 
-**Purpose:** How to define a spell (YAML/JSON schema, arguments, steps, variable interpolation) and a reference for the nine built-in step command types. For execution mechanics (running, dry-run, error codes, pause/resume, layering, credentials), see `.claude/guidance/moflo-spell-runner.md`.
+**Purpose:** How to define a spell (YAML/JSON schema, arguments, steps, variable interpolation) and a reference for the built-in step command types. For execution mechanics (running, dry-run, error codes, pause/resume, layering, credentials), see `.claude/guidance/moflo-spell-runner.md`.
 
 ---
 
@@ -96,16 +96,16 @@ steps:
     config:
       command: "curl -s {args.api_url}"
   - id: process
-    type: agent
+    type: bash
     config:
-      prompt: "Analyze this response: {fetch-url.stdout}"
+      command: 'claude -p "Analyze this response: {fetch-url.stdout}"'
 ```
 
 ---
 
 ## Step Command Types
 
-**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. To add new step types via JS/TS files, YAML composite steps, or `moflo-step-*` npm packages, see `.claude/guidance/moflo-spell-custom-steps.md`.
+**Fifteen built-in step types are registered automatically** (one of them, `agent`, is registered but not executable — see below). Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. To add new step types via JS/TS files, YAML composite steps, or `moflo-step-*` npm packages, see `.claude/guidance/moflo-spell-custom-steps.md`.
 
 ### bash — Run a Shell Command
 
@@ -122,18 +122,21 @@ steps:
 
 ---
 
-### agent — Spawn a Claude Subagent
+### agent — NOT EXECUTABLE
+
+**Do not use this step type.** It has never spawned a subagent — moflo has no agent spawner in the spell runner. It is still registered so existing spell YAML keeps parsing, but casting it now always fails with an explanatory error (#1334). Earlier versions returned `success: true` and a `result` string for work that never happened.
+
+**To run a Claude subagent from a spell, use a `bash` step:**
 
 ```yaml
 - id: research
-  type: agent
+  type: bash
   config:
-    agentType: "researcher"     # Required. researcher, coder, tester, etc.
-    prompt: "Find all API endpoints in {args.directory}"  # Required.
-    background: false           # Optional. Default false.
+    command: 'claude -p "Find all API endpoints in {args.directory}"'
+    timeout: 300000
 ```
 
-**Outputs:** `result` (string), `agentType` (string), `prompt` (string).
+**Outputs:** none — the step always fails. `agentType` and `prompt` are echoed in the failure for diagnosis only.
 
 ---
 

package/.claude/guidance/shipped/moflo-spell-runner.md

@@ -93,6 +93,40 @@ const result = loadSpellByName('deploy-staging', { /* same options */ });
 
 **Set `continueOnError: true` on a step to keep running after failure.** The failed step is recorded in results but execution continues. Without this flag, a step failure triggers rollback of completed steps and terminates the spell.
 
+### retry
+
+**Add a `retry` block to a step that can fail transiently — a flaky HTTP call, a rate limit, a momentary network drop.** Without it, one transient failure discards every completed step in the run. This matters most on the scheduled path, where a run dying at step 7 of 9 at 3am produces a failed record and no work.
+
+```yaml
+- id: fetch-report
+  type: http
+  retry:
+    attempts: 3          # total attempts INCLUDING the first
+    backoffMs: 1000      # base delay before attempt 2; doubles thereafter
+    maxDelayMs: 30000    # optional: ceiling on any single delay
+    maxTotalDelayMs: 60000  # optional: ceiling on the sum of all delays
+```
+
+**Retry is opt-in per step and never applied by default.** Blanket retry is wrong for non-idempotent work — silently re-running a step that posts to Slack or writes a file is worse than failing. A step with no `retry` block runs exactly once, exactly as before.
+
+**Only non-deterministic failures are retried.**
+
+| Failure | Retried? | Why |
+|---------|----------|-----|
+| Step returned failure / threw | Yes | The classic transient case |
+| Step timed out | Yes | May succeed when the upstream recovers |
+| Capability violation, unknown step type, invalid config | No | Deterministic — N attempts produce one outcome at N times the cost |
+| Auth-shaped error (401, expired token) | No | Owned by the credential-refresh path below, which can actually fix it |
+| Cancelled | No | The run is already tearing down |
+
+**Backoff is bounded twice and interruptible.** Each delay is capped by `maxDelayMs`, their sum by `maxTotalDelayMs` (60s default) — so `attempts: 50` cannot stall a scheduled run. Once the aggregate budget is spent, remaining attempts run back-to-back rather than being cancelled. The wait also aborts on the run's signal, so a wall-clock ceiling breach (`spells.budget.*.maxWallClockMs`) cuts a backoff short instead of being served after it. Delays carry ±10% jitter so a `parallel` block of steps hitting the same rate limit does not retry in lockstep.
+
+**Each attempt is billed independently.** A retried step that spawns `claude -p` consumes one `maxModelInvocations` reservation per attempt — retry and the spend ceiling compose, and the ceiling wins.
+
+**`attempts` appears in the step result** only when the step declared a `retry` block, so a step that succeeded on attempt 3 is distinguishable from one that succeeded immediately, and records for existing spells are unchanged.
+
+An unrecognised key inside `retry` is a validation error, not a silent "no retry" — the same failure direction the budget block uses.
+
 ---
 
 ## Pause and Resume

package/.claude/guidance/shipped/moflo-spell-scheduling.md

@@ -87,6 +87,35 @@ Practical floors:
 
 ---
 
+## Bounding Spend on Unattended Runs
+
+**Set `spells.budget.scheduled` before scheduling any spell that invokes `claude -p`.** A scheduled run is unattended: nothing observes how many times it calls the model, so a loop step or a too-frequent cron can spend without a signal until the bill arrives. `flo init` writes these values into new projects; existing projects are untouched on upgrade and must opt in.
+
+```yaml
+spells:
+  budget:
+    scheduled:
+      maxModelInvocations: 30     # `claude -p` spawns allowed per run
+      maxWallClockMs: 2400000     # 40 minutes end to end
+      dailyModelInvocations: 300  # rolling 24h across ALL scheduled runs
+```
+
+| Ceiling | Scope | Enforced | On breach |
+|---------|-------|----------|-----------|
+| `maxModelInvocations` | One run | Reservation before the process spawns | The spawn is refused — a denied invocation is never billed |
+| `maxWallClockMs` | One run | Deadline timer on the run's abort signal | The in-flight step is aborted |
+| `dailyModelInvocations` | Every run in this project, trailing 24h | Reservation checked against the on-disk ledger | The spawn is refused before the process starts |
+
+**Set `dailyModelInvocations`, not just the per-run keys — a per-run ceiling cannot bound a schedule.** The two answer different questions. A per-run ceiling asks "did this run go haywire"; the daily one asks "is this project spending more than I meant to." A five-minute cron under a 30-invocation per-run cap satisfies the per-run check 288 times a day and still reaches 8,640 invocations. Only the rolling window sees the total.
+
+The count persists in `.moflo/spell-invocation-ledger.json` and is checked **before** the per-run ceiling, so a breach message names the limit that actually stopped the run. Delete the file to reset the window; a corrupt or unreadable ledger fails open rather than blocking every scheduled run.
+
+**A breach aborts the run and ignores `continueOnError`.** It surfaces three ways: a `BUDGET_EXCEEDED` error on the result, `abortReason: budget-exceeded` plus a structured `budgetBreach` in the run's `tasklist` record, and a warning line in the daemon log.
+
+**This is a proxy for spend, not a measurement of it.** moflo counts invocations, not tokens — metering would require changing what a bash step returns to downstream steps, and `claude -p "say hi"` counts the same as `claude -p "refactor this subsystem"`. Use `spells.budget.interactive` (configured separately, never inherited from `scheduled`, and deliberately loose because a human is present) to cap session-attached runs, and a per-spell `budget:` block to tighten a single spell. Full key reference: `.claude/guidance/moflo-yaml-reference.md`.
+
+---
+
 ## Storage Namespaces
 
 **Two memory namespaces back the scheduler.** Both are project-scoped — schedules and history don't leak across projects.
@@ -221,5 +250,6 @@ If step 5 is empty, jump straight to the failure-modes table above — don't loo
 - `.claude/guidance/moflo-spell-engine.md` — Definition format, step types, variable interpolation
 - `.claude/guidance/moflo-spell-runner.md` — Execution lifecycle, dry-run, layering, errors
 - `.claude/guidance/moflo-spell-sandboxing.md` — Capability levels (`read`/`hooks`/`swarm`) referenced by the `mofloLevel` cap
+- `.claude/guidance/moflo-yaml-reference.md` — Full `spells.budget` key reference and the per-spell `budget:` block
 - `.claude/guidance/moflo-spell-troubleshooting.md` — Broader spell failure-mode catalog beyond scheduling
 - `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, daemon, MCP reference hub