moflo 4.9.19 → 4.9.21

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

@@ -15,46 +15,16 @@ npm install moflo
 npx flo init          # Interactive setup wizard
 ```
 
-`flo init` does the following:
-
-1. Creates `moflo.yaml` with detected project settings
-2. Sets up `.claude/settings.json` hooks (SessionStart, pre-edit, etc.)
-3. Configures `.mcp.json` for MCP tool access
-4. Copies the agent bootstrap guide to `.claude/guidance/`
-5. Injects a memory search section into CLAUDE.md
+`flo init` creates `moflo.yaml`, sets up `.claude/settings.json` hooks, configures `.mcp.json` for MCP tools, copies bootstrap guidance to `.claude/guidance/`, and injects a memory-search section into `CLAUDE.md`.
 
 ### Post-Install
 
 ```bash
-npx flo-setup         # Copy bootstrap guidance, inject CLAUDE.md section
+npx flo-setup         # Re-copy bootstrap guidance, re-inject CLAUDE.md section
 npx flo doctor --fix  # Verify everything is working
 ```
 
-For the full schema of `moflo.yaml` and the env-var overrides, see `moflo-yaml-reference.md`.
-
----
-
-## Building from Source
-
-**Full instructions: [`docs/BUILD.md`](../../../docs/BUILD.md)** — the canonical, step-by-step build/test/publish process. Always follow it.
-
-Quick reference (from project root only):
-
-```bash
-git pull origin main                   # ALWAYS pull first
-npm run build                          # tsc -b (project references)
-npm test                               # 0 failures required
-npm version patch --no-git-tag-version # Bump + sync cli version
-npm run build                          # Rebuild with new version
-npm publish --otp=XXX                  # Requires 2FA OTP
-```
-
-**Critical rules:**
-
-- npm only — no pnpm, yarn, or bun
-- Always build from root (`npm run build`) — never cd into subdirectories
-- Never publish without a successful build — `prepublishOnly` masks failures
-- Never publish without tests passing
+For the full schema of `moflo.yaml` and env-var overrides, see `.claude/guidance/moflo-yaml-reference.md`. (Building moflo itself from source is a maintainer concern — see `docs/BUILD.md`.)
 
 ---
 
@@ -64,31 +34,28 @@ When a Claude Code session starts, moflo automatically runs three background ind
 
 | Indexer | Command | Namespace | What it does |
 |---------|---------|-----------|--------------|
-| Guidance | `npx flo-index` | `guidance` | Chunks markdown docs, builds RAG links, generates 384-dim embeddings |
+| Guidance | `npx flo-index` | `guidance` | Chunks markdown, builds RAG links, generates 384-dim embeddings |
 | Code Map | `npx flo-codemap` | `code-map` | Scans source for types, interfaces, exports, directory structure |
 | Learning | `npx flo-learn` | `patterns` | Pattern research on codebase for cross-session learning |
 
 These run in background and are incremental (unchanged files are skipped). Controlled by `auto_index` in `moflo.yaml`.
 
-### Helper Script Auto-Sync
+### Session-Start Cost Expectations
 
-On version change, `session-start-launcher.mjs` copies helper scripts from the installed moflo package to the consumer project's `.claude/helpers/` and `.claude/scripts/` directories. This ensures hooks always run the latest version.
+The launcher does more than copy helpers — it also heals the memory DB, runs embeddings migrations, recycles the daemon when the install changes, and self-heals `.claude/settings.json` hook wiring. Expected timing:
 
-**Rule: static files, not dynamic generation.** If a helper script has no dynamic content (no per-project interpolation), it must be shipped as a pre-built static file in `bin/` and synced via the session-start file lists. Do not generate static content dynamically at runtime — it adds fragile moving parts (background `init --upgrade`, race conditions with session-start exit) and causes stale scripts when the sync list is incomplete.
+| Scenario | Cost | What you'll see |
+|----------|------|-----------------|
+| Steady-state start (no version change) | < 200 ms | Silent; no `moflo:` lines |
+| First start after `npm install moflo` | A few seconds (one-shot) | `moflo:` lines reporting synced files, daemon recycle, manifest write |
+| Major upgrade with embeddings migration | 30–60 s (one-shot) | Progress bar on stderr; cannot be skipped |
+| Slow on every start | Manifest drift loop | Run `flo doctor --fix` |
 
-| Source | Target | Files |
-|--------|--------|-------|
-| `bin/` | `.claude/scripts/` | `hooks.mjs`, `session-start-launcher.mjs`, `index-guidance.mjs`, `build-embeddings.mjs`, `generate-code-map.mjs`, `semantic-search.mjs` |
-| `bin/` | `.claude/helpers/` | `gate.cjs`, `gate-hook.mjs`, `prompt-hook.mjs`, `hook-handler.cjs` |
-| `src/cli/.claude/helpers/` | `.claude/helpers/` | `auto-memory-hook.mjs`, `statusline.cjs`, `subagent-start.cjs`, `pre-commit`, `post-commit` |
-
-When adding a new helper script: generate it once, save it to `bin/`, and add it to the appropriate list in `session-start-launcher.mjs`.
-
-**The full picture.** Helper sync is one of several things the launcher does on every session start. For the complete lifecycle (DB heal, embeddings migration, daemon recycling, settings.json self-heal, etc.) see `moflo-session-start.md`. For the contract on what moflo writes into `.claude/settings.json` and how surgical hook-wiring rewrites work, see `moflo-settings-injection.md`.
+For the contract on what moflo writes into `.claude/settings.json` and how surgical hook-wiring rewrites work, see `.claude/guidance/moflo-settings-injection.md`.
 
 ### Bundled Guidance
 
-Moflo ships its own guidance files (in `.claude/guidance/` within the package). When installed as a dependency, these are **automatically indexed** alongside the consumer project's guidance under the `guidance` namespace. This means agents in your project can search for moflo system docs (swarm patterns, memory commands, etc.) without any extra setup.
+Moflo ships its own guidance files inside the package. When installed as a dependency they are **automatically indexed** alongside the consumer project's guidance under the `guidance` namespace — agents can search for moflo system docs (swarm patterns, memory commands, etc.) without extra setup.
 
 ---
 
@@ -117,33 +84,23 @@ Moflo ships its own guidance files (in `.claude/guidance/` within the package).
 
 ## MCP Tools Setup
 
-MCP tools are the preferred way for Claude to interact with moflo. `flo init` writes `.mcp.json` in the project root automatically (see `moflo-yaml-reference.md` for the file's content and the global-registration alternative).
-
-This gives Claude access to ~125 MCP tools (`mcp__moflo__memory_*`, `mcp__moflo__hooks_*`, `mcp__moflo__swarm_*`, `mcp__moflo__moflodb_*`, etc.) without any global installation.
+`flo init` writes `.mcp.json` in the project root automatically (see `.claude/guidance/moflo-yaml-reference.md` for the file's content and the global-registration alternative). This gives Claude access to ~125 MCP tools (`mcp__moflo__memory_*`, `mcp__moflo__hooks_*`, `mcp__moflo__swarm_*`, `mcp__moflo__moflodb_*`, etc.) without any global installation.
 
-### Policy: every shipped MCP tool must have a real consumer (#693)
-
-We do not ship speculative tools. Every tool registered in `src/cli/mcp-tools/` must satisfy at least one of these:
-
-1. Referenced as `mcp__moflo__<name>` in a skill, agent file, doc, or guidance .md
-2. Called via `callMCPTool('<name>')` from CLI command code
-3. On the explicit allowlist in `src/cli/__tests__/mcp-tools-drift-guard.test.ts` with a justification (e.g. "expert API for `moflodb_*` controllers" or "advertised in `moflo-init.ts` CLAUDE.md fragment")
-
-The drift-guard test fails CI if a new tool is registered with no consumer and no allowlist entry. If you ship a tool, ship a real call site for it (or document why it has none).
+**Every shipped MCP tool has a real consumer call site** (skill, agent, doc, CLI code, or allowlist entry with justification). The drift-guard test in `src/cli/__tests__/mcp-tools-drift-guard.test.ts` fails CI if a new tool is registered with no consumer — moflo does not ship speculative tools.
 
 ---
 
 ## Project Config (Anti-Drift Defaults)
 
-- **Topology**: hierarchical (prevents drift)
-- **Max Agents**: 8 (smaller = less drift)
-- **Strategy**: specialized (clear roles)
-- **Consensus**: raft
-- **Memory**: hybrid
-- **HNSW**: Enabled
-- **Neural**: Enabled
+- **Topology:** hierarchical (prevents drift)
+- **Max Agents:** 8 (smaller = less drift)
+- **Strategy:** specialized (clear roles)
+- **Consensus:** raft
+- **Memory:** hybrid
+- **HNSW:** Enabled
+- **Neural:** Enabled
 
-For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox config, see `moflo-yaml-reference.md`. For the catalog of commands, agents, hooks, and consensus topologies these defaults shape, see `moflo-cli-reference.md`.
+For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox config, see `.claude/guidance/moflo-yaml-reference.md`. For the catalog of commands, agents, hooks, and consensus topologies these defaults shape, see `.claude/guidance/moflo-cli-reference.md`.
 
 ---
 
@@ -151,123 +108,49 @@ For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox confi
 
 ### Before Starting Coding Tasks
 
-**MCP (Preferred):** `mcp__moflo__memory_search` — `query: "[task keywords]", namespace: "patterns"`
+**MCP (preferred):** `mcp__moflo__memory_search` — `query: "[task keywords]"`, `namespace: "patterns"`.
 
-**CLI Fallback:**
+**CLI fallback:** `npx flo memory search --query '[task keywords]' --namespace patterns`.
 
-```bash
-npx flo memory search --query '[task keywords]' --namespace patterns
-```
-
-### After Completing Any Task Successfully (MCP Preferred)
+### After Completing Any Task
 
 | Step | MCP Tool | Key Params |
 |------|----------|------------|
-| 1. Store pattern | `mcp__moflo__memory_store` | `namespace: "patterns", key: "[name]", value: "[what worked]"` |
-| 2. Train neural | `mcp__moflo__hooks_post-edit` | `file: "[main-file]", trainNeural: true` |
-| 3. Record completion | `mcp__moflo__hooks_post-task` | `taskId: "[id]", success: true, storeResults: true` |
+| Store pattern | `mcp__moflo__memory_store` | `namespace: "patterns", key: "[name]", value: "[what worked]"` |
+| Train neural | `mcp__moflo__hooks_post-edit` | `file: "[main-file]", trainNeural: true` |
+| Record completion | `mcp__moflo__hooks_post-task` | `taskId: "[id]", success: true, storeResults: true` |
 
 ### Continuous Improvement Triggers
 
-| Trigger                | Worker     | When to Use                |
-|------------------------|------------|----------------------------|
-| After major refactor   | `optimize` | Performance optimization   |
-| After adding features  | `testgaps` | Find missing test coverage |
-| After security changes | `audit`    | Security analysis          |
-| After API changes      | `document` | Update documentation       |
-| Every 5+ file changes  | `map`      | Update codebase map        |
-| Complex debugging      | `deepdive` | Deep code analysis         |
+| Trigger | Worker | Use For |
+|---------|--------|---------|
+| After major refactor | `optimize` | Performance optimization |
+| After adding features | `testgaps` | Find missing test coverage |
+| After security changes | `audit` | Security analysis |
+| After API changes | `document` | Update documentation |
+| Every 5+ file changes | `map` | Update codebase map |
+| Complex debugging | `deepdive` | Deep code analysis |
 
 ### Memory-Enhanced Development
 
-**ALWAYS check memory before:**
-
-- Starting a new feature (search for similar implementations)
-- Debugging an issue (search for past solutions)
-- Refactoring code (search for learned patterns)
-- Performance work (search for optimization strategies)
-
-**ALWAYS store in memory after:**
-
-- Solving a tricky bug (store the solution pattern)
-- Completing a feature (store the approach)
-- Finding a performance fix (store the optimization)
-- Discovering a security issue (store the vulnerability pattern)
-
----
-
-## Memory Commands Reference (MCP Preferred)
+| Action | When |
+|--------|------|
+| Search memory before writing code | Starting a new feature, debugging an issue, refactoring, performance work |
+| Store in memory after solving | Tricky bug, completed feature, perf fix, security finding |
 
-### Store Data
-
-**MCP:** `mcp__moflo__memory_store`
-
-- Required: `key`, `value`
-- Optional: `namespace` (default: "default"), `ttl`, `tags`
-
-**CLI Fallback:**
-
-```bash
-npx flo memory store --key "pattern-auth" --value "JWT with refresh tokens" --namespace patterns
-```
-
-### Search Data (semantic vector search)
-
-**MCP:** `mcp__moflo__memory_search`
-
-- Required: `query`
-- Optional: `namespace`, `limit`, `threshold`
-
-**CLI Fallback:**
-
-```bash
-npx flo memory search --query "authentication patterns" --namespace patterns --limit 5
-```
-
-### List Entries
-
-**MCP:** `mcp__moflo__memory_list`
-
-- Optional: `namespace`, `limit`
-
-### Retrieve Specific Entry
-
-**MCP:** `mcp__moflo__memory_retrieve`
-
-- Required: `key`
-- Optional: `namespace` (default: "default")
+For namespaces, embedding model, indexing pipeline, and writing guidance that retrieves well, see `.claude/guidance/moflo-memory-strategy.md`.
 
 ---
 
-## Claude Code vs MCP vs CLI Tools
-
-### Claude Code Handles ALL EXECUTION:
-
-- **Task tool**: Spawn and run agents concurrently
-- File operations (Read, Write, Edit, Glob, Grep)
-- Code generation and programming
-- Bash commands and system operations
-- Git operations
+## Claude Code vs MCP vs CLI
 
-### MCP Tools Handle Coordination (Preferred):
-
-| Operation | MCP Tool |
-|-----------|----------|
-| Swarm init | `mcp__moflo__swarm_init` |
-| Agent spawn | `mcp__moflo__agent_spawn` |
-| Memory store | `mcp__moflo__memory_store` |
-| Memory search | `mcp__moflo__memory_search` |
-| Hooks (all) | `mcp__moflo__hooks_<hook-name>` |
-
-### CLI Commands (Fallback Only):
-
-Only use CLI via Bash when MCP tools are unavailable:
-
-```bash
-npx flo <command> [options]
-```
+| Layer | Handles | Examples |
+|-------|---------|----------|
+| Claude Code (execution) | Spawning agents, file ops, code, bash, git | `Task`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash` |
+| MCP tools (coordination — preferred) | Swarm/agent orchestration, memory, hooks | `mcp__moflo__swarm_init`, `mcp__moflo__agent_spawn`, `mcp__moflo__memory_store`, `mcp__moflo__hooks_*` |
+| CLI (fallback only) | Same coordination via shell when MCP unavailable | `npx flo <command> [options]` |
 
-**KEY**: MCP tools coordinate strategy, Claude Code's Task tool executes with real agents.
+**Key:** MCP tools coordinate strategy; Claude Code's `Task` tool executes with real agents.
 
 ---
 
@@ -279,32 +162,31 @@ Checks: Node version (20+), Git, config validity, daemon status, memory database
 
 ---
 
-## Troubleshooting Common Issues
+## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | No MCP tools available | `.mcp.json` missing or moflo not installed | Run `npx flo init` or manually create `.mcp.json` |
-| Memory search returns nothing | Indexer hasn't run yet | Run `npx flo-index --force` to index guidance |
-| Low search quality | Guidance docs missing `**Purpose:**` lines or generic headings | Follow guidance optimization rules in `moflo-memory-strategy.md` |
-| Session start slow | All three indexers running | Set `auto_index.code_map: false` in `moflo.yaml` if code map not needed |
+| Memory search returns nothing | Indexer hasn't run yet | Run `npx flo-index --force` |
+| Low search quality | Guidance docs missing `**Purpose:**` lines or generic headings | See `.claude/guidance/moflo-guidance-rules.md` |
+| Session start slow | All three indexers running | Set `auto_index.code_map: false` in `moflo.yaml` if not needed |
 | Status line not showing | `statusline.cjs` error or `status_line.enabled: false` | Run `node .claude/helpers/statusline.cjs` to test, check `moflo.yaml` |
-| Embeddings fail on first run (offline / air-gapped) | `fastembed` model cache missing | Pre-populate `~/.cache/fastembed` or set `FASTEMBED_CACHE` to a pre-baked cache dir — see `docs/modules/embeddings.md` "Sandbox & air-gapped first-run" |
+| Embeddings fail offline / air-gapped | `fastembed` model cache missing | Pre-populate `~/.cache/fastembed` or set `FASTEMBED_CACHE` (see `docs/modules/embeddings.md`) |
 | `flo` command not found | Not in PATH | Use `npx flo` or `node node_modules/moflo/bin/index-guidance.mjs` |
-| Bundled guidance not indexed | Running inside moflo repo (same dir) | Bundled guidance only indexes when installed as a dependency in a different project |
+| Bundled guidance not indexed | Running inside the moflo repo | Bundled guidance only indexes when installed as a dependency in a different project |
 
-See `moflo-memory-strategy.md` for memory-specific troubleshooting.
+See `.claude/guidance/moflo-memory-strategy.md` for memory-specific troubleshooting and `.claude/guidance/moflo-spell-troubleshooting.md` for spell sandbox/network failures.
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-cli-reference.md` — CLI commands, agents, hooks, hive-mind, RuVector
-- `.claude/guidance/shipped/moflo-yaml-reference.md` — `moflo.yaml` schema, environment variables, `.mcp.json` setup
-- `.claude/guidance/shipped/moflo-subagents.md` — Subagents memory-first protocol and store patterns
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — Task & swarm coordination with TaskCreate/TaskUpdate
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — Database schema, namespaces, search commands, RAG linking
-- `.claude/guidance/shipped/moflo-memorydb-maintenance.md` — Reindexing, namespace purging, recovery
-- `.claude/guidance/shipped/moflo-session-start.md` — Complete session-start lifecycle (DB heal, sync, migrations, daemon)
-- `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/` and how surgical self-heal works
-- `.claude/guidance/shipped/moflo-cross-platform.md` — Windows/macOS/Linux portability rules for any code change
-- `.claude/guidance/shipped/moflo-verbose-command-filtering.md` — Filter long verbose commands at the source; never tee-then-grep
+- `.claude/guidance/moflo-cli-reference.md` — CLI commands, agents, hooks, hive-mind, RuVector
+- `.claude/guidance/moflo-yaml-reference.md` — `moflo.yaml` schema, environment variables, `.mcp.json` setup
+- `.claude/guidance/moflo-subagents.md` — Subagents memory-first protocol and store patterns
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — Task & swarm coordination with TaskCreate/TaskUpdate
+- `.claude/guidance/moflo-memory-strategy.md` — Database schema, namespaces, search commands, RAG linking
+- `.claude/guidance/moflo-memorydb-maintenance.md` — Reindexing, namespace purging, recovery
+- `.claude/guidance/moflo-settings-injection.md` — What moflo writes into `.claude/` and how surgical self-heal works
+- `.claude/guidance/moflo-cross-platform.md` — Windows/macOS/Linux portability rules for any code change
+- `.claude/guidance/moflo-verbose-command-filtering.md` — Filter long verbose commands at the source; never tee-then-grep

package/.claude/guidance/shipped/moflo-cross-platform.md

@@ -163,4 +163,4 @@ Before submitting any code change, verify:
 ## See Also
 
 - `CLAUDE.md` — Consumer project checklist, build rules
-- `.claude/guidance/shipped/moflo-source-hygiene.md` — Source code hygiene rules
+- `.claude/guidance/moflo-source-hygiene.md` — Source code hygiene rules

package/.claude/guidance/shipped/moflo-error-handling.md

@@ -45,7 +45,7 @@
 
 ## Transient Errors Must Use Retry + Circuit Breaker
 
-**Wrap every transient-failure-capable operation in a retry helper with exponential backoff and a circuit breaker.** One-shot try-and-log on a transient class strands users in partial-state loops (#854: Windows file-lock + AV scan race left stale `.claude/helpers/gate.cjs` across 8+ moflo bumps).
+**Wrap every transient-failure-capable operation in a retry helper with exponential backoff and a circuit breaker.** One-shot try-and-log on a transient class strands users in partial-state loops — a representative incident: a Windows file-lock + AV scan race left stale `.claude/helpers/gate.cjs` across 8+ moflo bumps because each per-version sync swallowed the EBUSY without retrying.
 
 | Element | Default |
 |---------|---------|
@@ -70,5 +70,5 @@ if (!result.ok) syncFailures.push({ key, message: `${errMessage(result.err)} (re
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-source-hygiene.md` — General source code standards
-- `.claude/guidance/shipped/moflo-cross-platform.md` — Cross-platform rules
+- `.claude/guidance/moflo-source-hygiene.md` — General source code standards
+- `.claude/guidance/moflo-cross-platform.md` — Cross-platform rules

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

@@ -74,13 +74,23 @@ TaskCreate({
 
 ## 5. Keep Files Under 500 Lines
 
-Long guidance files lose effectiveness because:
+**The 500-line cap applies to every `.claude/guidance/**/*.md` file AND every `.claude/skills/*/SKILL.md` entry file.** The same RAG/attention math applies to both:
 
-- RAG chunking splits them, and chunks lose cross-section context
+- RAG chunking splits long files, and chunks lose cross-section context
 - Claude deprioritizes content deep in a long document
 - Competing chunks from the same file dilute search relevance
+- For SKILL.md, the **entire file is loaded into context on every invocation** — every extra line is a per-invocation token cost across all consumers
 
-If a doc exceeds 500 lines, split by concern into separate files. Each file should cover one topic thoroughly rather than many topics shallowly.
+If a doc exceeds 500 lines, split by concern. Two patterns:
+
+| Pattern | Where it fits | Example |
+|---------|---------------|---------|
+| **Sibling files** (guidance) | Topical split — each file owns one concern | `moflo-spell-engine.md` + `moflo-spell-runner.md` + `moflo-spell-troubleshooting.md` |
+| **Progressive disclosure** (skills) | Entry SKILL.md links to companions in the same skill directory | `spell-builder/SKILL.md` (entry) + `architecture.md` + `permissions.md` + `preflight.md` (companions) |
+
+Companion files are NOT auto-loaded — Claude reads them only when the SKILL.md entry directs it to. This keeps the per-invocation cost low while preserving the depth.
+
+A gating test (`skill-and-guidance-size-drift.test.ts`) enforces the cap and will fail CI if a guidance doc or SKILL.md entry exceeds 500 lines. Companion files inside a skill directory are exempt because they only load on demand.
 
 ---
 
@@ -137,8 +147,8 @@ Use relative names (not absolute paths) so the links work across project context
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — Companion rules on namespaces, RAG indexing, and search patterns the data feeds
-- `.claude/guidance/shipped/moflo-task-icons.md` — UX rule for `TaskCreate` and `Agent` description fields (ICON + [Role])
-- `.claude/guidance/shipped/moflo-user-facing-language.md` — How to phrase any text shown to end users (plain risk-level language, no jargon)
-- `.claude/guidance/shipped/moflo-subagents.md` — Memory-first protocol any guidance you write should reinforce
+- `.claude/guidance/moflo-memory-strategy.md` — Companion rules on namespaces, RAG indexing, and search patterns the data feeds
+- `.claude/guidance/moflo-task-icons.md` — UX rule for `TaskCreate` and `Agent` description fields (ICON + [Role])
+- `.claude/guidance/moflo-user-facing-language.md` — How to phrase any text shown to end users (plain risk-level language, no jargon)
+- `.claude/guidance/moflo-subagents.md` — Memory-first protocol any guidance you write should reinforce
 - `.claude/skills/guidance/SKILL.md` — `/guidance` skill that helps you author or audit guidance against these rules