moflo 4.9.20 → 4.9.22

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

@@ -0,0 +1,149 @@
+# Spell Troubleshooting — Sandbox, Network, and Permission Failures
+
+**Purpose:** Diagnostic playbook for spell step failures that look like environmental issues but are actually capability/sandbox boundaries. Reference this when a step "should work" but produces DNS errors, silent no-ops, or confusing downstream failures. Pair with `.claude/guidance/moflo-spell-sandboxing.md` for the underlying enforcement model.
+
+---
+
+## Bash Step Fails With DNS / SSH Resolution Errors
+
+The single most common spell failure mode. The step works fine in your normal shell, then fails inside a spell with what looks like a network/DNS problem.
+
+### Typical Error Messages
+
+- `ssh: Could not resolve hostname github.com: Temporary failure in name resolution`
+- `fatal: Could not read from remote repository.`
+- `curl: (6) Could not resolve host ...`
+- `getaddrinfo ENOTFOUND ...`
+- Any other DNS/connection failure where the **same command works in your normal shell**.
+
+### Tell-Tale Clue
+
+The error mentions `Temporary failure in name resolution` — a **glibc-specific** wording. That means the step is running inside a Linux sandbox (`bwrap` on Linux / WSL), **not** your outer shell. Git Bash or PowerShell won't produce that exact message.
+
+### Root Cause
+
+`src/cli/spells/core/bwrap-sandbox.ts` isolates the network by default:
+
+```ts
+if (!hasNet && !needsToolHomeAccess(options.permissionLevel)) {
+  args.push('--unshare-net');   // ← no network, no DNS
+}
+```
+
+A bash step gets network access **only when one of these is true**:
+
+1. The step declares a `net` capability, **or**
+2. The step's `permissionLevel` is `elevated` or `autonomous`.
+
+If neither applies, bwrap runs the command in a namespace with `--unshare-net`, and DNS silently fails. **There is no log line announcing the network was taken away** — you just see the command's own DNS error.
+
+### Fix
+
+For any bash step that does `git pull` / `git push` / `git fetch`, `gh` API calls, `curl`, `npm install`, or any other outbound network call:
+
+```yaml
+- id: create-branch
+  type: bash
+  permissionLevel: elevated       # ← grants network in bwrap
+  config:
+    command: "git pull origin main && ..."
+```
+
+Or declare the `net` capability explicitly if the step doesn't need the full `elevated` profile. **Note:** `bash-command.ts` must include `net` in its declared capabilities for the engine to accept the grant — otherwise you'll see:
+
+```
+Capability violation: step type "bash" does not declare capability "net"
+```
+
+### Quick Diagnosis Checklist
+
+When a spell's bash step can't reach the network, walk through these in order:
+
+| # | Question | If yes |
+|---|----------|--------|
+| 1 | Does the same command work in your outer shell? | Sandbox-related, not config — go to #2 |
+| 2 | Is the error wording glibc-style (`Temporary failure in name resolution`)? | bwrap is involved — go to #3 |
+| 3 | Does the failing step have `permissionLevel: elevated` or a `net` capability? | If no, add one and retry |
+| 4 | Does the multi-command step start with `set -e`? | If no, add it (see § Multi-Command `set -e` Traps below) |
+
+---
+
+## Multi-Command `set -e` Traps
+
+A bash step that chains multiple statements without `set -e` will **return exit code 0 even when the real work failed**, producing confusing errors several steps later.
+
+### Symptom
+
+A spell step appears to succeed (`exitCode: 0`), but a later step fails with something that should have been impossible — typically:
+
+- `pathspec did not match` on a branch that was never created
+- `nothing to commit` when you expected staged changes
+- File operations on paths that don't exist
+
+### Root Cause
+
+Without `set -e`, a multi-command bash step like this:
+
+```yaml
+- id: prep-branch
+  type: bash
+  config:
+    command: "git pull origin main && git checkout -b feat/x && git stash pop || true"
+```
+
+…will mask a failure in `git pull` (e.g. blocked by `--unshare-net`) because the trailing `git stash pop || true` returns 0 for the whole step. Downstream steps assume the branch exists and produce the confusing `pathspec` error.
+
+### Fix
+
+Lead every multi-command bash step with `set -e`:
+
+```yaml
+- id: prep-branch
+  type: bash
+  permissionLevel: elevated
+  config:
+    command: |
+      set -e
+      git pull origin main
+      git checkout -b feat/x
+      git stash pop || true   # only this one is allowed to fail
+```
+
+`set -e` makes the shell exit on any non-zero status, surfacing the real failure at the right step.
+
+---
+
+## Capability Violation Errors
+
+When a spell YAML restricts capabilities a command doesn't declare, or grants new types beyond the command's defaults, the runner blocks execution before the step runs.
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `Capability violation: step type "X" does not declare capability "Y"` | YAML restricts a capability the step command doesn't list | Add `Y` to the step command's `capabilities` array (in code), or remove the restriction from YAML |
+| `CAPABILITY_DENIED at runtime` | A command tried to access a path/host outside its effective scope | Tighten the command, or widen the YAML capability scope to include the resource |
+
+See `.claude/guidance/moflo-spell-sandboxing.md` § Enforcement at Runtime for the two-layer enforcement model.
+
+---
+
+## Step Silently No-Ops
+
+A step appears to run (`exitCode: 0`), produces no output, and downstream steps act as if no work happened.
+
+| Likely cause | Diagnostic |
+|--------------|------------|
+| Command writes to stdout but bwrap blocks the working directory | Check `permissionLevel`; bwrap restricts `fs:write` to declared scopes |
+| Variable interpolation produced an empty string | Run with `dryRun: true` to see resolved configs (see `moflo-spell-runner.md`) |
+| `continueOnError: true` is hiding a real failure | Remove `continueOnError` temporarily, re-run, inspect error output |
+| Trailing `|| true` on the only critical statement | Restructure with `set -e` and place `|| true` only on cleanup statements |
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability types, enforcement layers, permission levels (the model these failures exercise)
+- `.claude/guidance/moflo-spell-engine.md` — Step definition format and types
+- `.claude/guidance/moflo-spell-runner.md` — Dry-run validation, error codes, pause/resume
+- `.claude/guidance/moflo-yaml-reference.md` — `sandbox:` block in `moflo.yaml` (master toggle, tier selection)
+- `src/cli/spells/core/bwrap-sandbox.ts` — Source for `--unshare-net` and namespace setup
+- `src/cli/spells/core/permission-resolver.ts` — Capability → permission level derivation

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

@@ -1,150 +1,79 @@
-# MoFlo Subagents Guide
+# MoFlo Subagents — Spawn Protocol
 
-**Purpose:** Protocol for subagents spawned by coordinators. Follow these steps before doing any work.
+**Purpose:** Steps every subagent MUST run when spawned by a coordinator. The single-sentence directive injected by `SubagentStart` (see `.claude/helpers/subagent-bootstrap.json`) tells every subagent to memory-search first, then follow this protocol. Universal coding/coordination rules every agent (coordinator OR subagent) shares live in `.claude/guidance/moflo-agent-rules.md` — read those after Step 1.
 
 ---
 
-## 1. Search Memory FIRST
+## Step 1: Search Memory FIRST
 
-**Before reading any files or exploring code, search memory for guidance relevant to your task.**
+**Before reading any files or exploring code, search memory.** This is the bootstrap action — moflo's gates will block your `Glob`/`Grep`/`Read` calls until you do.
 
-### Namespaces to search:
-
-| Namespace | When to search | What it returns |
-|-----------|---------------|-----------------|
-| `guidance` | always | Guidance docs, coding rules, domain context |
-| `patterns` | always | Learned patterns from previous task execution |
-| `learnings` | always | User-directed decisions + distilled insights (post-mortems, gotchas, lessons learned) |
-| `code-map` | navigating code | Project overviews, directory contents, type-to-file mappings |
-| `tests` | test/coverage queries | Indexed test inventory — pinpoint specs and coverage for a given function/module |
-
-**Always search `patterns` and `learnings` alongside `guidance`.** Patterns hold solutions to already-solved problems; learnings hold incident insights and user-stated decisions. Skipping either means repeating past mistakes or violating standing decisions.
-
-**Search `code-map` BEFORE using Glob/Grep for navigation.** It's faster and returns structured results including file-level type mappings.
-
-**Search `tests` when looking for test coverage** of a function, module, or behavior — it indexes the test tree separately so you can pinpoint specs without grepping the whole repo.
-
-### Option A: MCP Tools (Preferred)
-
-If you have MCP tools available (check for `mcp__moflo__*`), use them directly:
-
-| Tool | Purpose |
-|------|---------|
-| `mcp__moflo__memory_search` | Semantic search with domain-aware embeddings |
-| `mcp__moflo__memory_store` | Store patterns with auto-vectorization |
-| `mcp__moflo__hooks_route` | Get agent routing suggestions |
-
-### Option B: CLI via Bash
-
-```bash
-npx flo memory search --query "[describe your task]" --namespace guidance --limit 5
+```
+mcp__moflo__memory_search   query: "[describe your task]"   namespace: "guidance"
 ```
 
-| Your task involves... | Search namespace | Example query |
-|-----------------------|------------------|---------------|
-| Database/entities | `guidance` + `patterns` + `learnings` | `"database entity migration"` |
-| Frontend components | `guidance` + `patterns` + `learnings` | `"React frontend component"` |
-| API endpoints | `guidance` + `patterns` + `learnings` | `"API route endpoint pattern"` |
-| Authentication | `guidance` + `patterns` + `learnings` | `"auth middleware JWT"` |
-| Prior solutions/gotchas | `patterns` + `learnings` | `"audit log service pattern"` |
-| Past incident/lesson | `learnings` | `"windows postinstall file locks"` |
-| Where is a file/type? | `code-map` | `"CompanyEntity file location"` |
-| What's in a directory? | `code-map` | `"back-office api routes"` |
-| Tests for a function | `tests` | `"audit log service tests"` |
-| Coverage for a module | `tests` | `"auth middleware test cases"` |
-
-Use results with score > 0.3. If no good results, fall back to reading project guidance docs.
-
----
-
-## 2. Check for Project-Specific Overrides
+Run the search **at least three times** — once each against `guidance`, `patterns`, and `learnings`. Patterns hold prior solutions; learnings hold standing decisions and post-mortem insights. Skipping either repeats past mistakes. Add `code-map` when navigating code, `tests` when looking for test coverage.
 
-Claude Code automatically loads all `.claude/guidance/*.md` files into your context. If the consuming project has its own guidance files (e.g., domain rules, entity patterns, tech stack conventions), they are already available to you — no need to read them manually.
+CLI fallback when MCP is unavailable: `npx flo memory search --query "..." --namespace guidance --limit 5`.
 
-Project-specific guidance always takes precedence over generic MoFlo guidance.
+The full namespace reference, query examples by domain, and tool catalog live in `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — read that next.
 
 ---
 
-## 3. Universal Rules
-
-### Memory Protocol
-- Search memory before exploring files
-- Store discoveries back to memory when done
-- Use `patterns` namespace for solutions and gotchas
-- Use `learnings` namespace for architectural choices, user-requested decisions, and distilled insights (`knowledge` is a deprecated alias — writes are auto-redirected)
+## Step 2: Apply Universal Agent Rules
 
-### Git/Branches
-- Use conventional commit prefixes: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
-- Use branch prefixes: `feature/`, `fix/`, `refactor/`
-- Use kebab-case for branch names
+Every moflo agent — coordinator or subagent — must follow `.claude/guidance/moflo-agent-rules.md`. The most load-bearing rules for subagents specifically:
 
-### Pull Requests — CRITICAL: Always target the correct repo
-**NEVER run bare `gh pr create` in a forked repository.** The `gh` CLI defaults to the upstream parent repo, not the fork's origin. This has caused PRs to be accidentally opened against upstream.
+| Rule | Detail |
+|------|--------|
+| **Task Icons** | `TaskCreate` MUST use **ICON + [Role]** in `subject` and `activeForm` — see `.claude/guidance/moflo-task-icons.md`. Example: `🧪 [Tester] Run unit tests` / activeForm: `🧪 Running unit tests` |
+| **PR target repo (CRITICAL)** | Never run bare `gh pr create` in a forked repo — it defaults to upstream. Always pass `--repo "$REPO"`. Full workflow in `moflo-agent-rules.md` |
+| **MCP-first tool selection** | Prefer `mcp__moflo__*` tools over `npx flo` CLI. CLI is fallback only |
+| **Build & test after changes** | Never leave failing tests; fix red signals at the source |
 
-**Required workflow:**
-```bash
-# 1. Determine the correct repo from the origin remote
-REPO=$(git remote get-url origin | sed 's|.*github.com[:/]||;s|\.git$||')
-
-# 2. ALWAYS pass --repo to gh pr create
-gh pr create --repo "$REPO" --title "..." --body "..."
-
-# 3. For merge: also pass --repo
-gh pr merge <number> --repo "$REPO" --squash
-```
+The full set (git/branch conventions, file organization, build/test discipline, storing discoveries) is in `.claude/guidance/moflo-agent-rules.md`.
 
-This applies to ALL `gh` commands that target a repo: `pr create`, `pr merge`, `pr list`, `issue create`, etc.
+---
 
-### File Organization
-- Never save working files to repository root
-- Keep changes focused (3-10 files)
-- Stay within feature scope
+## Step 3: Check for Project-Specific Overrides
 
-### Build & Test
-- Build and test after code changes
-- Never leave failing tests
+Claude Code automatically loads all `.claude/guidance/*.md` files into your context. If the consuming project has its own guidance files (domain rules, entity patterns, tech-stack conventions), they're already available — no need to read them manually.
 
-### Task Icons (MANDATORY)
-- `TaskCreate` MUST use **ICON + [Role]** in `subject` and `activeForm`
-- Full icon map: `.claude/guidance/shipped/moflo-task-icons.md`
-- Example: `🧪 [Tester] Run unit tests` / activeForm: `🧪 Running unit tests`
+**Project-specific guidance always takes precedence over generic MoFlo guidance.**
 
 ---
 
-## 4. Store Discoveries
+## Step 4: Store Discoveries Before Reporting
 
-If you discover something new (pattern, solution, gotcha), store it:
+Before signing off your work, store anything useful you discovered during the task. Future agents shouldn't have to re-discover what you already learned.
 
-### MCP (Preferred):
-```
-mcp__moflo__memory_store
-  namespace: "patterns"
-  key: "brief-descriptive-key"
-  value: "1-2 sentence insight"
-```
+| Namespace | What to store |
+|-----------|---------------|
+| `patterns` | Solutions to tricky bugs, gotchas, workarounds |
+| `learnings` | Architectural choices, user-stated decisions, post-mortem insights |
 
-### CLI Fallback:
-```bash
-npx flo memory store --namespace patterns --key "brief-descriptive-key" --value "1-2 sentence insight"
-```
+**Store:** Patterns that worked, gotchas you hit, workarounds for limitations.
+**Skip:** Generic summaries of retrieved guidance, restated rules, trivial file-location notes.
 
-**Store:** Solutions to tricky bugs, patterns that worked, gotchas, workarounds
-**Skip:** Summaries of retrieved guidance, general rules, file locations
+See `.claude/guidance/moflo-agent-rules.md` § Storing Discoveries for the full MCP/CLI invocation patterns.
 
 ---
 
-## 5. When Complete
+## Step 5: When Complete
+
+1. Report findings to the coordinator
+2. Confirm any discoveries are stored (Step 4)
+3. The coordinator will mark your task `completed` via `TaskUpdate`
 
-1. Report findings to coordinator
-2. Store learnings if you discovered something new
-3. Coordinator will mark your task as completed
+Do not mark your own task completed — that's the coordinator's responsibility.
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-task-icons.md` — Mandatory ICON + [Role] format for every `TaskCreate` and `Agent` description spawned by a coordinator
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarm coordinators cooperate when subagents are spawned in batches
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — The memory-search-first rule this protocol enforces, with namespace-selection guidance
-- `.claude/guidance/shipped/moflo-memorydb-maintenance.md` — How the memory namespaces are populated and refreshed; required reading when search returns no results
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Full CLI/MCP reference including the spell gates that block subagent spawn before memory is searched
+- `.claude/guidance/moflo-agent-rules.md` — Universal rules every agent (coordinator OR subagent) shares
+- `.claude/guidance/moflo-task-icons.md` — Mandatory ICON + [Role] format for every `TaskCreate` and `Agent` description
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — How task lists and swarm coordinators cooperate when subagents are spawned in batches
+- `.claude/guidance/moflo-memory-strategy.md` — Memory architecture, namespaces, search patterns
+- `.claude/guidance/moflo-memorydb-maintenance.md` — How memory namespaces are populated and refreshed
+- `.claude/guidance/moflo-core-guidance.md` — Full CLI/MCP reference including the spell gates that block subagent spawn before memory is searched

package/.claude/guidance/shipped/moflo-task-icons.md

@@ -66,7 +66,7 @@ The spinner is the primary visual feedback during agent execution. Without icons
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-subagents.md` — Subagent protocol; `TaskCreate`/`Agent` icon rule is enforced as part of the spawning checklist
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarms cooperate; icons distinguish swarm-spawned vs single-agent work
-- `.claude/guidance/shipped/moflo-user-facing-language.md` — Companion UX rule for any text shown to end users
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Spell Gate that enforces icon format on `TaskCreate`
+- `.claude/guidance/moflo-subagents.md` — Subagent protocol; `TaskCreate`/`Agent` icon rule is enforced as part of the spawning checklist
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — How task lists and swarms cooperate; icons distinguish swarm-spawned vs single-agent work
+- `.claude/guidance/moflo-user-facing-language.md` — Companion UX rule for any text shown to end users
+- `.claude/guidance/moflo-core-guidance.md` — Spell Gate that enforces icon format on `TaskCreate`

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

@@ -37,6 +37,6 @@
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-task-icons.md` — Companion UX rule: spinner text must use ICON + [Role] so non-technical users can identify the working agent
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Permission disclosure output where this language rule has the largest user-visible surface
-- `.claude/guidance/shipped/moflo-error-handling.md` — Sibling rule for what error messages must contain; this doc governs how those messages are phrased
+- `.claude/guidance/moflo-task-icons.md` — Companion UX rule: spinner text must use ICON + [Role] so non-technical users can identify the working agent
+- `.claude/guidance/moflo-spell-sandboxing.md` — Permission disclosure output where this language rule has the largest user-visible surface
+- `.claude/guidance/moflo-error-handling.md` — Sibling rule for what error messages must contain; this doc governs how those messages are phrased

package/.claude/guidance/shipped/moflo-verbose-command-filtering.md

@@ -35,11 +35,11 @@ npm run build -- --verbose 2>&1 | grep -E "error TS|Failed|Cannot find"
 
 ## Why It Matters
 
-Case study: issue #903 burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
+A representative incident burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline
+- `.claude/guidance/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
+- `.claude/guidance/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -184,8 +184,7 @@ Global registration is useful for ad-hoc projects where you don't want to commit
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub: getting started, anti-drift defaults, troubleshooting
-- `.claude/guidance/shipped/moflo-cli-reference.md` — Commands, agents, hooks, hive-mind, ruvector — the surfaces this config gates
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — What `sandbox:` actually does at the bash-step boundary, with capability/permission interaction
-- `.claude/guidance/shipped/moflo-session-start.md` — Where these config fields are read and applied during session start
-- `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/settings.json` (the hook wiring; complementary to `moflo.yaml` toggles)
+- `.claude/guidance/moflo-core-guidance.md` — Hub: getting started, anti-drift defaults, troubleshooting
+- `.claude/guidance/moflo-cli-reference.md` — Commands, agents, hooks, hive-mind, ruvector — the surfaces this config gates
+- `.claude/guidance/moflo-spell-sandboxing.md` — What `sandbox:` actually does at the bash-step boundary, with capability/permission interaction
+- `.claude/guidance/moflo-settings-injection.md` — What moflo writes into `.claude/settings.json` (the hook wiring; complementary to `moflo.yaml` toggles)