moflo 4.9.9 → 4.9.11

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

@@ -0,0 +1,144 @@
+# Guidance Rules — Writing Guidance Claude Will Actually Follow
+
+**Purpose:** The universal rules for writing `.claude/guidance/**/*.md` documents that Claude parses, follows, and indexes most effectively. Reference this whenever you create or revise a guidance file in your project. The rules below are the same ones moflo follows for its own shipped guidance.
+
+---
+
+## 1. Structure for Scanability
+
+Claude processes guidance as part of a large context window alongside code, tool results, and conversation history. Guidance competes for attention.
+
+- **Lead with a `**Purpose:**` line** immediately after the H1. One sentence stating what this doc is for and when to use it. This is the single most important line — it determines whether Claude keeps reading or skips.
+- **Use H2 sections as entry points.** Claude may land in the middle of a doc via RAG chunk retrieval. Each H2 should be independently understandable without reading prior sections.
+- **Front-load the actionable rule, then explain.** Put the instruction first, rationale second. Claude acts on instructions; it uses rationale to resolve ambiguity.
+
+```markdown
+## Good
+**Always search memory before Glob/Grep.** Memory search is 150x faster and returns
+domain-aware results that Glob cannot provide.
+
+## Bad
+Memory search uses HNSW indexing with domain-aware embeddings that provide much better
+results than file-system search tools. Because of this, you should search memory first.
+```
+
+---
+
+## 2. Be Imperative, Not Descriptive
+
+Claude follows instructions better than it infers behavior from descriptions. Write rules as direct commands.
+
+| Pattern | Example |
+|---------|---------|
+| Imperative (preferred) | **Use `mcp__moflo__memory_search` before Glob/Grep** |
+| Descriptive (weaker) | The memory search tool can be used to find guidance |
+| Passive (weakest) | Memory should be searched before file exploration |
+
+---
+
+## 3. Use Tables for Decision Logic
+
+When guidance involves conditional behavior (if X then Y), tables are parsed faster and more reliably than prose or nested bullet lists.
+
+```markdown
+| Condition | Action |
+|-----------|--------|
+| Background agent | TaskCreate required |
+| 2+ parallel agents | TaskCreate for each |
+| Single foreground, simple task | Skip TaskCreate |
+```
+
+Avoid encoding decision trees in paragraph form. Claude frequently drops branches from prose-encoded conditionals.
+
+---
+
+## 4. Code Examples Must Be Concrete
+
+Abstract examples get ignored. Concrete examples with realistic values get followed.
+
+```markdown
+## Good
+TaskCreate({
+  subject: "🔍 Investigate failing booking tests",
+  activeForm: "🔍 Investigating test failures"
+})
+
+## Bad
+TaskCreate({
+  subject: "[icon] [description of task]",
+  activeForm: "[icon] [present participle of task]"
+})
+```
+
+---
+
+## 5. Keep Files Under 500 Lines
+
+Long guidance files lose effectiveness because:
+
+- RAG chunking splits them, and chunks lose cross-section context
+- Claude deprioritizes content deep in a long document
+- Competing chunks from the same file dilute search relevance
+
+If a doc exceeds 500 lines, split by concern into separate files. Each file should cover one topic thoroughly rather than many topics shallowly.
+
+---
+
+## 6. Headings Must Be Specific
+
+RAG retrieval uses heading text as the primary signal for chunk relevance. Generic headings produce poor search results.
+
+| Generic (bad) | Specific (good) |
+|---------------|----------------|
+| Overview | Architecture: Two-Layer Task + Swarm Model |
+| Configuration | Anti-Drift Swarm Configuration |
+| Examples | Non-Swarm TaskCreate Examples |
+| Rules | Pull Request Target Repo Rules |
+
+---
+
+## 7. Anti-Patterns in Guidance
+
+| Anti-pattern | Why it fails | Fix |
+|-------------|-------------|-----|
+| Repeating the same rule in multiple files | Claude encounters conflicting phrasings and picks arbitrarily | Single source of truth, cross-reference via See Also |
+| Long preambles before the first rule | Claude may stop reading before reaching actionable content | Purpose line, then rules, then explanation |
+| Embedding rules inside code comments | RAG indexes headings and prose, not code comments | State the rule in prose, then show the code |
+| Using "should" / "consider" / "might want to" | Hedged language gets deprioritized vs. firm instructions | Use "must" / "always" / "never" for critical rules |
+| Documenting what Claude already knows | Wastes context window and dilutes novel instructions | Only document project-specific rules and non-obvious constraints |
+
+---
+
+## 8. Optimize for RAG Chunking
+
+Guidance files are chunked by heading boundaries and indexed with embeddings for semantic search. To maximize retrieval quality:
+
+- **Every H2 section should have a self-contained opening sentence** summarizing the section's purpose. This becomes the chunk's embedding anchor.
+- **Keep sections between 5–30 lines.** Shorter than 5 lines lacks context for useful embeddings. Longer than 30 lines gets truncated or split mid-thought.
+- **Avoid orphan content** — text between the H1 and first H2 that isn't under any heading. It gets chunked with minimal heading context, producing poor embeddings.
+- **Use `---` horizontal rules between major sections.** These are chunk boundary hints.
+
+---
+
+## 9. See Also Sections
+
+End every guidance file with a `## See Also` section linking related docs. This helps Claude navigate between related concerns and helps RAG link related chunks.
+
+```markdown
+## See Also
+
+- `.claude/guidance/<other-doc>.md` — One-line description of why this is related
+- `.claude/guidance/<other-doc>.md` — Use Title Case "See Also" (not "See also")
+```
+
+Use relative names (not absolute paths) so the links work across project contexts.
+
+---
+
+## 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/skills/guidance/SKILL.md` — `/guidance` skill that helps you author or audit guidance against these rules

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

@@ -261,3 +261,4 @@ npx flo memory search --query "your domain query" --namespace guidance  # Verify
 - `moflo-subagents.md` — Subagents guide
 - `moflo-claude-swarm-cohesion.md` — Task & swarm coordination
 - `moflo-core-guidance.md` — Full CLI/MCP reference
+- Internal-only: `internal/guidance-sync.md` — Mechanics of how shipped guidance reaches the DB and the search index, including cleanup paths for stale content

package/.claude/guidance/shipped/moflo-memorydb-maintenance.md

@@ -1,10 +1,15 @@
 # Memory Database Maintenance
 
+**Purpose:** How to inspect, reindex, and recover the moflo memory database. Reference this when memory search returns empty results, embeddings look stale, or you need to purge a namespace before re-running an indexer.
+
+---
+
 ## Database Location
 
-- **Path:** `.swarm/memory.db`
+- **Path:** `.moflo/moflo.db` — canonical post-#727 location
 - **Engine:** sql.js (WASM-based SQLite — no native binaries needed)
 - **Single table:** `memory_entries` — stores content, embeddings, and metadata in one table
+- **Legacy path:** `.swarm/memory.db` — pre-#727 consumers may still have this. The launcher migrates it to `.moflo/moflo.db` automatically on session start. After migration the legacy file is renamed `.swarm/memory.db.bak` and is safe to delete once you've verified the canonical DB is healthy (`flo doctor`).
 
 ## Schema
 
@@ -68,7 +73,7 @@ node bin/build-embeddings.mjs
 
 ## Purging a Namespace
 
-Use sql.js directly (no sqlite3 binary on this machine):
+Use sql.js directly (no sqlite3 binary required):
 
 ```js
 node --input-type=module -e "
@@ -76,7 +81,7 @@ import initSqlJs from 'sql.js';
 import { readFileSync, writeFileSync } from 'fs';
 
 const SQL = await initSqlJs();
-const buf = readFileSync('.swarm/memory.db');
+const buf = readFileSync('.moflo/moflo.db');
 const db = new SQL.Database(buf);
 
 // Check counts before
@@ -89,11 +94,13 @@ db.run(\"DELETE FROM memory_entries WHERE namespace = 'code-map'\");
 const after = db.exec('SELECT namespace, COUNT(*) FROM memory_entries GROUP BY namespace');
 console.log('AFTER:', JSON.stringify(after[0]?.values));
 
-writeFileSync('.swarm/memory.db', Buffer.from(db.export()));
+writeFileSync('.moflo/moflo.db', Buffer.from(db.export()));
 db.close();
 "
 ```
 
+> **Important — sql.js write-back clobbers manual edits.** Long-lived processes (the moflo daemon, MCP servers) read the DB once on startup and dump the entire in-memory state on every flush. Direct `node -e` writes against `.moflo/moflo.db` while the daemon is running will be overwritten the next time it flushes. Run `flo daemon stop` (or stop your editor's MCP session) before purging, then restart afterwards.
+
 After purging, reindex the namespace and rebuild embeddings:
 ```bash
 node bin/generate-code-map.mjs   # or whichever indexer owns the namespace
@@ -102,10 +109,30 @@ node bin/build-embeddings.mjs
 
 ## Auto-Reindex on Session Start
 
-`hooks.mjs` spawns `index-all.mjs` on session start, which runs the full chain. This only works if `index-all.mjs` is in the `scriptFiles` array in `session-start-launcher.mjs` (see docs/BUILD.md § "Adding New Scripts").
+`hooks.mjs` spawns `index-all.mjs` on session start, which runs the full chain. This only works if `index-all.mjs` is in the `scriptFiles` array in `session-start-launcher.mjs` (see `moflo-session-start.md` § "Helper script sync").
+
+## Recovering From a Legacy DB
+
+If you find an older `.swarm/memory.db` (or a post-upgrade `.swarm/memory.db.bak`) with learnings/knowledge entries that didn't migrate cleanly, cherry-pick them into the canonical DB:
+
+```bash
+flo memory restore-learnings --from .swarm/memory.db
+flo memory restore-learnings --from .swarm/memory.db.bak
+```
 
 ## Troubleshooting
 
 - **Empty search results:** Run `mcp__moflo__memory_stats` to check entry counts. If a namespace is empty, run its indexer.
 - **Stale embeddings:** Run `node bin/build-embeddings.mjs` — it skips entries that already have embeddings unless content changed.
-- **Full reset:** Delete `.swarm/memory.db` and run `node bin/index-all.mjs && node bin/build-embeddings.mjs`.
+- **Wrong DB path used by tools:** Run `flo doctor` — it reports both canonical and legacy paths and flags drift.
+- **Full reset:** Stop the daemon, delete `.moflo/moflo.db`, then run `node bin/index-all.mjs && node bin/build-embeddings.mjs`.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — When to use which namespace; semantic search query patterns
+- `.claude/guidance/shipped/moflo-core-guidance.md` — `flo memory` CLI subcommands and `flo doctor` output
+- `.claude/guidance/shipped/moflo-session-start.md` — Where the auto-reindex chain runs in the launcher lifecycle
+- `.claude/guidance/shipped/moflo-subagents.md` — Memory-first protocol that depends on these indexes being healthy
+- `.claude/guidance/internal/guidance-sync.md` — Internal: how guidance content actually flows from `shipped/` into the DB and out to search (three-layer pipeline + cleanup paths)

package/.claude/guidance/shipped/moflo-session-start.md

@@ -0,0 +1,154 @@
+# MoFlo Session-Start Lifecycle
+
+**Purpose:** Document everything that runs when Claude Code fires the `SessionStart` hook in a moflo-enabled project. The launcher does substantially more than "start the daemon" — it heals stale state, migrates DBs, syncs scripts, and reconciles hook wiring. Knowing what runs (and in what order) makes diagnosis fast.
+
+**Audience:** Agents and developers diagnosing slow session starts, unexpected mutations to `.claude/`, embedded migrations, daemon recycling, and post-upgrade behaviour.
+
+---
+
+## Quick reference
+
+The launcher (`bin/session-start-launcher.mjs`, synced to `.claude/scripts/session-start-launcher.mjs`) is the single SessionStart hook moflo registers. Everything below runs in one process, in the listed order, before Claude Code begins the session. Total cost on a healthy install with no version change is typically < 200 ms; an upgrade or DB heal can extend it to several seconds.
+
+When anything runs, the launcher prints `moflo: <action> (<details>)` to stdout. Claude Code captures stdout as session-start `additionalContext`, so the agent sees every mutation. Failures land on stderr and similarly surface.
+
+---
+
+## Stages, in execution order
+
+### 0. Headless skip
+
+If `CLAUDE_CODE_HEADLESS=true` is set in the environment, the launcher exits immediately. The moflo daemon spawns headless Claude processes (for indexing, pretraining, etc.); without this guard each spawned Claude would re-enter the launcher and fork the indexer chain on every daemon worker tick. ([#860](https://github.com/eric-cielo/moflo/issues/860).)
+
+### 0-pre. Drop stale upgrade-notice files
+
+`.moflo/upgrade-notice.json` is a transient handshake between launcher and statusline. Pre-#738 launchers wrote a 1-hour-TTL "complete" notice that could survive past the launcher run that wrote it. The launcher unconditionally removes any leftover before its own run begins.
+
+### 0c. Memory DB index repair
+
+Probes `.moflo/moflo.db` for `sqlite_autoindex_memory_entries_1` corruption and runs `REINDEX` in place if found. Must run before any sql.js consumer (embeddings migration, ephemeral-namespace purge, MCP server, daemon) — those swallow corruption errors and silently drop work otherwise. Cost on the happy path: one PRAGMA check (~10 ms). ([#743](https://github.com/eric-cielo/moflo/issues/743).)
+
+### 0d. Clear post-install restart notice
+
+If `.moflo/restart-pending.json` was written by `scripts/post-install-notice.mjs` after the last `npm install moflo` and the running version now matches the pending version, the file is removed. The user has restarted; the notice has done its job. ([#867](https://github.com/eric-cielo/moflo/issues/867).)
+
+### 2. Reset workflow state
+
+Writes a fresh `.claude/workflow-state.json` for the new session: `tasksCreated: false`, `memorySearched: false`, `sessionStart: <ISO timestamp>`. The gate scripts read this on every tool call.
+
+### 3. Auto-sync on version change (or drift)
+
+This is the biggest stage. It fires when **either** condition is true:
+
+- The installed version (`node_modules/moflo/package.json`) differs from the cached version stamp (`.moflo/moflo-version`), OR
+- Any file in `.moflo/installed-files.json` (the manifest from the previous successful sync) is missing or has drifted in size since we last wrote it.
+
+When triggered, the launcher walks the following sub-steps in order:
+
+| Sub-step | What runs | Why |
+|---------|-----------|-----|
+| Stop daemon | Kills the daemon recorded in `.moflo/daemon.lock` | The daemon was started under the previous moflo image; old module-cache + path resolution would clobber the upgrade. ([#851](https://github.com/eric-cielo/moflo/issues/851).) |
+| Cherry-pick learnings | `cherry-pick-learnings.js` reads legacy `.swarm/memory.db` and `INSERT OR IGNORE`s into `.moflo/moflo.db` | Carries user-authored knowledge forward across the v3 DB rename. Idempotent. |
+| Sync scripts | Copy `bin/*.mjs` and `bin/lib/**` and `bin/migrations/**` into `.claude/scripts/` | Hooks always run the latest version |
+| Sync helpers | Copy `bin/{gate.cjs,gate-hook.mjs,prompt-hook.mjs,hook-handler.cjs}` plus `.claude/helpers/{auto-memory-hook.mjs,statusline.cjs,...}` into `.claude/helpers/` | Same |
+| Sync shipped guidance | Copy every `node_modules/moflo/.claude/guidance/shipped/moflo-*.md` into `.claude/guidance/`, prefixing each with the auto-generated mirror header | These are the files indexed by the consumer's memory namespace |
+| Cleanup retired files | Anything in the OLD manifest but NOT in the new manifest is unlinked | Auto-removes files moflo no longer ships |
+| Per-file retry/circuit | Each copy retries `[50, 200, 800] ms` on `EBUSY`/`EPERM`/`EACCES` (Windows file lock, AV scan); after 5 distinct failures the circuit opens and the rest of the sync runs without retries | Prevents a sick host from compounding wall-clock cost; persistent failures land on stderr |
+| Manifest write | New `{path, size}` manifest committed to `.moflo/installed-files.json` | Drift detection on next launcher run |
+| Defer version stamp | Pending write of `.moflo/moflo-version` queued for stage 3g | Stamp is "launcher fully completed" — writing it mid-flight strands consumers on a half-applied upgrade ([#730](https://github.com/eric-cielo/moflo/issues/730)) |
+
+### 3a-pre. Recycle stale daemons
+
+Even when the version hasn't changed, the daemon-lock's `startedAt` is compared against `node_modules/moflo`'s install mtime. If the daemon predates the current install (with a 5 s skew margin), it's recycled. This catches the "user upgraded ages ago, ran one session that bumped the stamp + recycled the daemon, but the daemon they started long-ago is still alive holding stale module cache" failure mode.
+
+### 3a. Settings.json migration and self-heal
+
+See `moflo-settings-injection.md` for the full mechanism. The launcher applies, in order:
+
+1. **Drop stale `PATH` override** — pre-4.x settings injected `${PATH}` which Claude Code didn't expand, breaking node resolution.
+2. **Replace `npx flo` hook commands with direct `node "$CLAUDE_PROJECT_DIR/..."` invocations** — saves 2–5 s of `npx` cold-start per hook.
+3. **Ensure `statusLine` is wired** — the helper script is synced by stage 3 but the config block may be absent.
+4. **Repair + rewrite hook wirings** — `repairHookWiring()` adds missing required hooks; `rewriteIncorrectHookWiring()` rewrites known-stale hook commands (e.g. [#879](https://github.com/eric-cielo/moflo/issues/879) `gate.cjs record-memory-searched` → `gate-hook.mjs record-memory-searched`).
+
+### 3b. Restore + prune shipped guidance mirrors
+
+Even when stage 3 didn't fire (no version change, no drift), the launcher checks that every `moflo-*.md` from `node_modules/moflo/.claude/guidance/shipped/` exists at `.claude/guidance/<file>` with the auto-generated mirror header. Missing files are restored; mirror files whose source has been removed (and which still carry the `<!-- AUTO-GENERATED by moflo session-start.` marker) are pruned. ([#839](https://github.com/eric-cielo/moflo/issues/839).)
+
+### 3b-714, 3c. Legacy cleanup
+
+- `.swarm/vector-stats.json` (replaced by `.moflo/vector-stats.json` post-#699) is unlinked.
+- Pre-4.8.45 double-prefixed guidance files (`moflo-moflo-*.md`) are unlinked.
+
+### 3d-yaml. Append missing top-level sections to `moflo.yaml`
+
+`bin/lib/yaml-upgrader.mjs` walks the user's `moflo.yaml` and idempotently appends any registered top-level section that's absent (e.g., `sandbox:`, `auto_update:`, `daemon:`). Never modifies user-set values; never reorders or reformats. Surfaces appended section names so the user can find what changed. (Pattern documented in `internal/upgrade-contract.md` "Yaml upgrade pattern".)
+
+### 3d. Install global `flo` shim
+
+Best-effort install of a shim into npm's global bin so bare `flo` resolves to the local project's `node_modules/.bin/flo`. Idempotent — skips when already present. Non-fatal on failure: `flo` still works via `npx`.
+
+### 3e. Foreground embeddings migration
+
+`runEmbeddingsMigrationIfNeeded` checks `.moflo/moflo.db` for embeddings-version drift and, if needed, re-embeds rows in chunks. Runs synchronously with piped stdio so the renderer's progress bar reaches the user. Returns fast (~ms) when no migration is needed.
+
+### 3e-728, 3e-729. Hard-purge legacy memory rows
+
+- Soft-deleted tombstones (status='deleted' rows from pre-#728 builds) are hard-deleted and the DB is VACUUMed.
+- Ephemeral-namespace rows (`hive-mind`, `tasklist`, `epic-state`, `test-bridge-fix`) accumulated by pre-#729 builds are hard-deleted; going forward, writes to those namespaces skip embedding generation entirely.
+
+Both run **before** the daemon is restarted in stage 4 so a concurrent sql.js flush can't clobber the foreground purge.
+
+### 3f. Flip upgrade notice to "completed"
+
+If stage 3 wrote an "in-progress" upgrade notice for the statusline, it's flipped to "completed" with a 2-minute TTL. The next session-start's stage 0-pre wipes any leftover.
+
+### 3g. Commit deferred version stamp
+
+`.moflo/moflo-version` is finally written with the installed version. Any abort above leaves the stamp unchanged so the next launcher re-detects the upgrade and re-runs stage 3. ([#730](https://github.com/eric-cielo/moflo/issues/730).)
+
+### 4. Spawn background tasks
+
+- `node bin/hooks.mjs session-start` is spawned detached + unref'd. That script starts the daemon, the indexer, the pretrain pass, the HNSW build, and the neural-pattern training. None of it blocks the session.
+- Migrations (`run-migrations.mjs`) consult `.moflo/migrations.json` and run any unmigrated steps synchronously, then announce completed migrations via `moflo:` mutation lines.
+
+### 5. Exit
+
+`process.exit(0)`. Claude Code now begins the session with the launcher's stdout captured as additionalContext.
+
+---
+
+## Diagnosing slow session starts
+
+Bottlenecks, in rough order of likelihood:
+
+| Symptom | Likely stage | Mitigation |
+|---------|-------------|------------|
+| Several-second delay on first start after `npm install` | Stage 3 (script + helper + guidance sync) | Expected — one-shot cost. Subsequent starts are ms. |
+| 30–60 s delay on first start after a major upgrade | Stage 3e (embeddings migration) | Surfaces a progress bar via stderr; cannot be skipped. |
+| Repeated multi-second delay on every start | Stage 3 firing every time = manifest drift loop | Check `moflo: repaired stale install` lines on stdout — usually means a file copy keeps failing (Windows AV, file lock). Run `flo doctor --fix`. |
+| Daemon appears to restart on every start | Stage 3a-pre — daemon predates install | Expected if you just upgraded; should stop after one session. |
+
+If a stage hangs, the launcher's per-step timeouts (5–30 s depending on the operation) protect against deadlock. A blocked stage that times out lands an error on stderr; the next launcher run retries.
+
+---
+
+## Adding a new stage (developer note)
+
+Before adding work to the launcher, ask:
+
+1. Is this **per-session** work (hook reset, mirror restore) or **per-version** work (script sync, manifest)? Per-version belongs in stage 3 under the version-change gate; per-session goes in stage 2 or as its own gated stage.
+2. Does it touch `sql.js`? It must run **before** stage 4's daemon spawn — concurrent flushes from a long-lived sql.js consumer will clobber a foreground write.
+3. Does it mutate consumer state? It must `emitMutation()` so the user sees what changed via additionalContext. Silent mutations are a regression of the upgrade contract.
+4. Does it depend on a fresh-state invariant (e.g., daemon stopped, manifest written, version stamp committed)? Order matters — see the existing 3 → 3a → 3a-pre → ... → 3g → 4 sequence and slot in accordingly.
+
+Full ordering rules and historical violations live in `internal/upgrade-contract.md`.
+
+---
+
+## See Also
+
+- `moflo-settings-injection.md` — the contract for what moflo writes into `.claude/settings.json` and how the surgical self-heal works.
+- `moflo-core-guidance.md` (Helper Script Auto-Sync) — the file lists for stage 3.
+- `moflo-memorydb-maintenance.md` — what runs against `.moflo/moflo.db` (embeddings, soft-delete, ephemeral purge).
+- Internal-only: `internal/upgrade-contract.md` — the "user must never re-run init" invariant the launcher enforces, with historical violations to learn from.
+- Internal-only: `internal/guidance-sync.md` — Stages 3 and 3b documented end-to-end as part of the three-layer guidance sync (filesystem → DB → HNSW).

package/.claude/guidance/shipped/moflo-settings-injection.md

@@ -0,0 +1,124 @@
+# How moflo Injects Into Claude Code
+
+**Purpose:** Explain what moflo writes into a consumer project's `.claude/` directory, when and how it auto-updates, and how the self-healing mechanism keeps existing installs current without manual `flo init` runs.
+
+**Audience:** Agents in consumer projects troubleshooting "why did my `.claude/settings.json` change?" or "is my hook wiring still correct after upgrading moflo?", and moflo developers preserving the upgrade contract.
+
+---
+
+## What moflo owns in your project
+
+Once moflo is installed (`npm install --save-dev moflo`) and `flo init` has been run, the following directory layout is moflo-managed:
+
+| Path | Owned by | Sync trigger | Editable by user? |
+|------|----------|--------------|-------------------|
+| `.claude/scripts/*.mjs`, `.claude/scripts/lib/**`, `.claude/scripts/migrations/**` | moflo | Version change OR file drift | No — overwritten on next session |
+| `.claude/helpers/*.cjs`, `.claude/helpers/*.mjs` | moflo | Version change OR file drift | No — overwritten on next session |
+| `.claude/guidance/moflo-*.md` (top-level mirror) | moflo | Every session start | No — auto-regenerated |
+| `.claude/guidance/shipped/**` (inside `node_modules/moflo`) | moflo | Frozen with the npm package | Read-only inside `node_modules` |
+| `.claude/settings.json` | shared | `flo init` writes; session-start patches surgically | Yes — moflo only fixes known-bad hook commands |
+| `moflo.yaml` | user | `flo init` creates; session-start appends missing top-level sections | Yes — moflo never modifies user-set values |
+| `CLAUDE.md` (block between markers) | moflo | Regenerated by `flo init`; left alone afterward unless you re-init | The moflo block only |
+| `.moflo/**` (state, db, manifests) | moflo | Runtime | Don't edit by hand |
+| `.swarm/**` (LEGACY) | moflo | Read-only recovery source | Safe to delete |
+
+The general principle: **tool-owned files get replaced; user-owned files get additive patches**. moflo never overwrites your `moflo.yaml` values, your CLAUDE.md content outside the moflo block, or hook commands you've personalised that don't match a known stale-pattern.
+
+---
+
+## Three sync mechanisms
+
+`bin/session-start-launcher.mjs` runs on every Claude Code session start (registered as a `SessionStart` hook in `.claude/settings.json`). It performs three different kinds of sync:
+
+### 1. Static file copy (scripts and helpers)
+
+For files with no per-project content (e.g., `gate.cjs`, `gate-hook.mjs`, `hook-handler.cjs`, `session-start-launcher.mjs` itself):
+
+- Each file is copied verbatim from `node_modules/moflo/bin/` (or `node_modules/moflo/.claude/helpers/`) into the consumer's `.claude/scripts/` or `.claude/helpers/`.
+- Triggered when `node_modules/moflo/package.json` `version` differs from the cached version stamp in `.moflo/moflo-version`, **or** when any previously-installed file has gone missing or changed size since the last successful sync (drift heal).
+- A manifest at `.moflo/installed-files.json` tracks `{path, size}` for every file we wrote. The next launcher uses it both to detect drift and to clean up retired files (anything in the old manifest but not the new one is deleted on upgrade).
+- Failures during copy (Windows file lock, AV real-time scan) are retried with `[50ms, 200ms, 800ms]` backoff and a 5-failure circuit breaker; persistent failures surface on stderr so you can run `flo doctor --fix` to repair.
+
+### 2. Generator-based output (settings.json, moflo.yaml top-level sections, CLAUDE.md block)
+
+Files that mix per-project content with shipped content:
+
+| File | Generator | When it runs | Behaviour on existing file |
+|------|-----------|--------------|----------------------------|
+| `.claude/settings.json` | `src/cli/init/settings-generator.ts` | `flo init` only | Doesn't overwrite — see surgical patch below |
+| `moflo.yaml` top-level sections | session-start launcher (yaml-upgrader) | Every session | Idempotently appends missing top-level keys with sensible defaults; never modifies user values |
+| `CLAUDE.md` moflo block | `src/cli/init/claudemd-generator.ts` | `flo init` only | Replaces only the marked block between begin/end comments |
+
+Once `flo init` has run, `.claude/settings.json` is your file. moflo's generator is the source-of-truth for what new consumers get, but existing consumers keep their personalised settings.
+
+### 3. Surgical patch (self-heal)
+
+This is what fixes existing consumers when moflo ships a hook wiring fix or a new required hook. It runs every session start and only touches what's known to be wrong, leaving everything else alone.
+
+Two passes share `src/cli/services/hook-wiring.ts`:
+
+| Pass | Function | What it does |
+|------|----------|--------------|
+| **Repair missing** | `repairHookWiring()` | Adds any required hook entry (`REQUIRED_HOOK_WIRING`) that isn't present in the consumer's settings. Idempotent — won't add duplicates. |
+| **Rewrite stale** | `rewriteIncorrectHookWiring()` | Applies known-fix substring rewrites (`HOOK_REWRITE_RULES`) to existing hook commands. Idempotent — a command already at the corrected form is a no-op. |
+
+A rewrite rule looks like:
+
+```ts
+{
+  name: '#879: record-memory-searched → gate-hook.mjs',
+  from: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" record-memory-searched',
+  to:   'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-memory-searched',
+}
+```
+
+If your `.claude/settings.json` has the `from` form, the launcher rewrites it to `to` and surfaces `moflo: updated .claude/settings.json (rewrote N stale hook wirings)` on stdout. Unrelated hooks you've added — custom loggers, project-specific gates, anything not on the known-fix list — are preserved.
+
+---
+
+## What gets surfaced to the user
+
+Whenever the launcher mutates anything, it prints to stdout (which Claude Code captures as `additionalContext` for the session). Each mutation is one line:
+
+```
+moflo: upgraded (4.9.5 → 4.9.10)
+moflo: updated .claude/settings.json (rewrote 2 stale hook wirings)
+moflo: starting background tasks (daemon, indexer, pretrain — CPU may briefly spike)
+```
+
+Failures land on stderr and similarly surface to the agent. If something silently fails, that's a bug — file an issue.
+
+---
+
+## How to opt out / customise
+
+| Goal | Mechanism |
+|------|-----------|
+| Disable the entire auto-update flow | Set `auto_update.enabled: false` in `moflo.yaml` |
+| Disable script syncing only | `auto_update.scripts: false` |
+| Disable helper syncing only | `auto_update.helpers: false` |
+| Customise a hook command moflo doesn't manage | Add it to a separate matcher block in `.claude/settings.json` — surgical rewrites only touch the specific `from` strings on the rule list |
+| Disable a moflo gate | Edit the matching block in `moflo.yaml` (e.g., `gates.memory_first: false`); the gate scripts honor these flags |
+
+Future versions may add hook-block-level locking to suppress drift detection wholesale — track [#881](https://github.com/eric-cielo/moflo/issues/881) for that umbrella.
+
+---
+
+## Troubleshooting
+
+**"My `.claude/settings.json` was modified after a session restart."** — Look at the launcher's stdout in the session-start additionalContext. The line beginning `moflo: updated .claude/settings.json` lists every change in plain English. If you don't recognise a rewrite, check the moflo issue tracker for the rule name (each `HOOK_REWRITE_RULES` entry includes the issue number, e.g. `#879`).
+
+**"Helper scripts disappeared from `.claude/helpers/`."** — The launcher tracks installed files via `.moflo/installed-files.json` and re-syncs missing ones on every start. Open and close a Claude Code session; if the file doesn't come back, check `.moflo/manifest` write permissions or run `flo doctor --fix`.
+
+**"Hooks ran but the gate isn't reset on new prompts."** — Verify `UserPromptSubmit` includes a hook calling `gate-hook.mjs prompt-reminder`. If missing, `repairHookWiring()` adds it on next session start. If still missing after restart, the gate may be running through `gate.cjs` directly — see issue [#879](https://github.com/eric-cielo/moflo/issues/879) for the wrapper-vs-direct distinction.
+
+**"I want to inspect what would be rewritten without actually changing my settings."** — The current launcher applies rewrites on every start. Manual dry-run isn't yet exposed; track [#881](https://github.com/eric-cielo/moflo/issues/881) for the planned drift-detection mode that surfaces diffs without applying them.
+
+---
+
+## See Also
+
+- `moflo-core-guidance.md` (Helper Script Auto-Sync section) — file lists and the static-files rule.
+- `moflo-cross-platform.md` — why hook commands always use `node "$CLAUDE_PROJECT_DIR/..."` paths.
+- Internal-only: `internal/upgrade-contract.md` documents the contract from a moflo-developer perspective, including the historical violations (sandbox, settings.json drift) that motivated the self-heal mechanism.
+- Internal-only: `internal/guidance-sync.md` — Sibling self-heal mechanism for shipped guidance content (this doc covers settings.json; that one covers the guidance pipeline).

package/.claude/guidance/shipped/moflo-source-hygiene.md

@@ -98,6 +98,6 @@ Before creating any new source file, verify:
 ## See Also
 
 - `CLAUDE.md` — Project-wide rules, consumer project checklist
-- `.claude/guidance/internal/guidance-rules.md` — Rules for writing guidance docs
+- `.claude/guidance/shipped/moflo-guidance-rules.md` — Rules for writing guidance docs
 - `docs/BUILD.md` — Build and publish process
 - `docs/adr/0001-collapse-moflo-workspace-packages.md` — The ADR that documents the collapse

package/.claude/guidance/shipped/moflo-spell-custom-steps.md

@@ -0,0 +1,126 @@
+# Spell Engine — Custom (Pluggable) Step Commands
+
+**Purpose:** How to extend the spell engine with user-defined or third-party step types. Reference when a built-in step type can't express what a spell needs and you want to drop in a `.js`/`.ts`/`.yaml` step file (or install an `moflo-step-*` npm package) instead of forking moflo.
+
+---
+
+## Pluggable Step Commands
+
+**Drop JS/TS or YAML files into a step directory to extend the spell engine with custom step types.** User-defined steps are auto-discovered and registered alongside built-in commands.
+
+### Discovery Sources (Priority Order)
+
+| Priority | Source | Path |
+|----------|--------|------|
+| Lowest | npm packages | `node_modules/moflo-step-*` |
+| Medium | Built-in | Registered by `createRunner()` |
+| Highest | User directories | `workflows/steps/` or `.claude/workflows/steps/` |
+
+**Later sources override earlier ones by step type name.** A user step named `bash` replaces the built-in `bash` command.
+
+---
+
+## JS/TS Step Files
+
+**Export a `StepCommand` object as the default export, or as `stepCommand` or `command` named export.**
+
+```javascript
+// workflows/steps/file-stats.js
+module.exports = {
+  type: 'file-stats',
+  description: 'Report file statistics',
+  configSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+  capabilities: [{ type: 'fs:read' }],
+  validate(config) {
+    const errors = [];
+    if (!config.path) errors.push({ path: 'path', message: 'path is required' });
+    return { valid: errors.length === 0, errors };
+  },
+  async execute(config) {
+    const { readFileSync, statSync } = require('node:fs');
+    const content = readFileSync(config.path, 'utf-8');
+    return { success: true, data: { lines: content.split('\n').length, bytes: statSync(config.path).size } };
+  },
+  describeOutputs() { return [{ name: 'lines', type: 'number' }, { name: 'bytes', type: 'number' }]; },
+};
+```
+
+See `examples/spell-steps/file-stats.js` for a complete, well-commented example.
+
+---
+
+## YAML Composite Steps
+
+**YAML files define reusable composite spell steps with declared inputs, tool dependencies, and sequential actions.**
+
+```yaml
+# workflows/steps/notify.yaml
+name: notify
+description: Log a formatted notification message
+inputs:
+  level:
+    type: string
+    required: false
+    default: "info"
+  message:
+    type: string
+    required: true
+actions:
+  - command: "echo [${inputs.level}] ${inputs.message}"
+```
+
+| YAML Field | Required | Description |
+|------------|----------|-------------|
+| `name` | Yes | Step type name (used as `type` in spell definitions) |
+| `description` | No | Human-readable description |
+| `tool` | No | Declares tool dependency (maps to `net` capability and prerequisites) |
+| `inputs` | No | Input schema with `type`, `required`, `default`, `description` per field |
+| `actions` | Yes | Sequential actions to execute; each has `tool`/`action`/`command` + `params` |
+
+**Use `${inputs.X}` in action params for input interpolation.** Required inputs are validated before execution.
+
+---
+
+## npm Package Discovery
+
+**Install a package named `moflo-step-*` and its exported StepCommand is auto-discovered.**
+
+The loader reads `package.json` for a `moflo.stepCommand` field pointing to the entry file. Falls back to the package's `main` field if absent.
+
+```json
+{
+  "name": "moflo-step-slack-notify",
+  "main": "index.js",
+  "moflo": { "stepCommand": "lib/step.js" }
+}
+```
+
+---
+
+## Configuring Step Discovery in createRunner
+
+**Pass `stepDirs` and `projectRoot` to `createRunner()` to enable pluggable step discovery.**
+
+```typescript
+import { createRunner } from 'moflo/dist/src/cli/spells/index.js';
+
+const runner = createRunner({
+  stepDirs: ['workflows/steps/', '.claude/workflows/steps/'],
+  projectRoot: process.cwd(),  // Enables npm moflo-step-* discovery
+});
+```
+
+---
+
+## Invalid Files Are Warnings, Not Errors
+
+**Files that don't export a valid StepCommand are skipped with a warning.** This prevents one bad file from breaking all step discovery. Invalid conditions: missing exports, wrong interface shape, syntax errors, malformed YAML.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-spell-engine.md` — Built-in step types, spell definition format, runner lifecycle, error codes
+- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Capability declarations a custom step must include and how the sandbox enforces them
+- `.claude/guidance/shipped/moflo-spell-connectors.md` — When to write a connector instead of a custom step (resource-shaped vs. action-shaped extension)
+- `.claude/guidance/shipped/moflo-spell-engine-architecture.md` — Architecture decisions for the pluggable step loader