moflo 4.9.20 → 4.9.21

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

@@ -1,57 +1,28 @@
 # Memory & Semantic Search Strategy
 
-**Purpose:** How memory, embeddings, and semantic search work in moflo. Reference when writing guidance documents, debugging search quality, configuring memory for a consumer project, or extending the system.
-
----
-
-## Problem Statement
-
-Claude Code agents need project-specific knowledge — coding rules, architecture patterns, entity templates, testing conventions — delivered at the right moment. Without a retrieval system, agents either miss critical rules or require massive CLAUDE.md files that waste context window tokens.
-
-**Goals:**
-- Agents find relevant guidance automatically via semantic search
-- Subagents spawned by the coordinator inherit memory access
-- Search quality is high enough that agents don't need to read whole files
-- The system survives `npm install` (indexing runs on session start)
+**Purpose:** How memory, embeddings, and semantic search work in moflo. Reference when debugging search quality, configuring memory for a project, or extending the indexing pipeline. Authoring rules for guidance docs themselves live in `.claude/guidance/moflo-guidance-rules.md` — read those first.
 
 ---
 
 ## Architecture Overview
 
-```
-Source Files (.claude/guidance/*.md, docs/*.md)
-         |
-         v
-index-guidance.mjs --- Chunk on ## headers, build RAG links
-         |                (prev/next, siblings, parent/child, context overlap)
-         v
-.swarm/memory.db ----- SQLite (entries + metadata + embedding vectors)
-         |
-         v
-build-embeddings.mjs - Generate 384-dim vectors per entry
-         |                (Xenova/all-MiniLM-L6-v2 neural, or domain-aware hash fallback)
-         v
-HNSW index ----------- Approximate nearest-neighbor search
-         v
-Search layer ---------- Three access paths:
-                          1. MCP tools (mcp__moflo__memory_search) -- preferred
-                          2. CLI (npx flo memory search) -- fallback
-                          3. Script (semantic-search.mjs) -- detailed output
-```
+Source files (`.claude/guidance/*.md`, `docs/**/*.md`, code, tests) flow through four stages:
 
-**Key files:**
+1. **Index** — `bin/index-*.mjs` chunks markdown on `##` headers and walks code/tests for structural facts
+2. **Store** — entries land in `.moflo/moflo.db` (SQLite via sql.js) with metadata + RAG links
+3. **Embed** — `bin/build-embeddings.mjs` generates 384-dim vectors via `fastembed` (mandatory, see ADR-EMB-001)
+4. **Search** — `mcp__moflo__memory_search` (preferred), `npx flo memory search` (fallback), or `npx flo-search` (verbose) hit an HNSW index for nearest-neighbor lookup
 
 | File | Purpose |
 |------|---------|
-| `.swarm/memory.db` | SQLite database with all entries, embeddings, metadata |
-| `.swarm/code-map-hash.txt` | SHA-256 hash for incremental code map skip |
+| `.moflo/moflo.db` | SQLite DB — entries, embeddings, metadata |
 | `.moflo/neural/patterns.json` | ReasoningBank learned patterns |
-| `bin/build-embeddings.mjs` | Generates 384-dim embeddings |
-| `bin/index-guidance.mjs` | Indexes guidance files with RAG linking |
-| `bin/generate-code-map.mjs` | Generates structural code map (projects, dirs, types, interfaces) |
-| `bin/index-patterns.mjs` | Extracts per-file code patterns |
-| `bin/index-tests.mjs` | Indexes test structure and patterns |
-| `bin/index-all.mjs` | Runs the full indexing chain sequentially |
+| `bin/index-guidance.mjs` | Indexes guidance with RAG linking |
+| `bin/generate-code-map.mjs` | Structural code map (projects, dirs, types) |
+| `bin/index-patterns.mjs` | Per-file code patterns |
+| `bin/index-tests.mjs` | Test structure |
+| `bin/index-all.mjs` | Runs the full chain sequentially |
+| `bin/build-embeddings.mjs` | Generates 384-dim vectors |
 
 ---
 
@@ -59,104 +30,44 @@ Search layer ---------- Three access paths:
 
 | Namespace | Content | Indexed By |
 |-----------|---------|------------|
-| `guidance` | Indexed guidance and docs | `index-guidance.mjs` |
-| `code-map` | Structural codebase index (projects, directories, types, interfaces) | `generate-code-map.mjs` |
-| `patterns` | Per-file code patterns (services, routes, error handling, exports) | `index-patterns.mjs` |
+| `guidance` | Markdown guidance and docs | `index-guidance.mjs` |
+| `code-map` | Structural codebase index (projects, dirs, types, interfaces) | `generate-code-map.mjs` |
+| `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` |
 
----
-
-## Guidance Document Optimization Rules
-
-These rules determine how well your guidance documents retrieve via semantic search:
-
-### 1. Every file needs a Purpose line
-
-Add `**Purpose:**` as the first meaningful line after the title. Claude checks this first for relevance scoring. Without it, the chunk has no summary signal.
-
-### 2. H2 headings are the primary retrieval signal
-
-The indexer splits on `##`. Each heading becomes the chunk title, prepended to searchable content. Domain-specific keywords in headings dramatically improve recall.
-
-**Bad:** `## Overview`, `## Rules`, `## Pattern`
-**Good:** `## Soft Delete Rules`, `## JWT Authentication Pattern`, `## Database Entity Migration`
-
-### 3. Ideal chunk size: 1000-4000 characters
-
-Below 50 chars the chunk is dropped. Above 6000 the indexer force-splits on paragraphs, which breaks mid-thought. The sweet spot produces focused embeddings.
-
-### 4. Self-contained chunks
-
-Each H2 section must answer a question without needing the rest of the document. Include: the rule, a code example, and a cross-reference.
-
-### 5. Tables over prose
-
-Claude parses structured data more accurately than paragraphs. DO/DON'T tables, field reference tables, and command tables all retrieve better.
-
-### 6. Cross-references create a navigation graph
-
-The RAG indexer stores `prevChunk`/`nextChunk`/`siblings` metadata. Cross-references between documents let Claude follow chains: `core.md -> coding-rules.md -> database.md`.
-
-### 7. No decorative formatting
-
-ASCII boxes, excessive emoji, rhetorical questions, and motivational text all waste tokens without improving retrieval or comprehension.
+Namespaces are independent indexes. Search defaults to `all`; pass `namespace: "guidance"` to target one.
 
 ---
 
 ## Embedding Strategy
 
-### Embedding Model
-
-| Model | Runtime | Speed | Notes |
-|-------|---------|-------|-------|
-| `fast-all-MiniLM-L6-v2` | `fastembed` (native ONNX + Rust tokenizer) | ~3s for 1000 entries | The only supported model — neural embeddings are mandatory (ADR-EMB-001) |
-
-**Neural embeddings (fast-all-MiniLM-L6-v2):**
-- Uses the `fastembed` npm package (Qdrant's embeddings-only ONNX client)
-- 384-dimensional vectors, L2-normalized
-- True semantic understanding — "soft delete" matches "mark as deleted" without keyword overlap
-- Model auto-downloads to `~/.cache/fastembed` on first use; cached for subsequent queries
-- For offline / air-gapped / sandboxed runs, pre-populate the cache or set `FASTEMBED_CACHE` — see `docs/modules/embeddings.md` "Sandbox & air-gapped first-run"
-
-**Legacy-compatible model names:** Entries embedded by earlier moflo versions may be tagged `Xenova/all-MiniLM-L6-v2` or `onnx`. These share the same vector space as `fast-all-MiniLM-L6-v2`, so search treats them as compatible (`semantic-search.mjs` `COMPATIBLE_MODELS`).
-
-**No hash fallback.** Epic #527 removed every hash-embedding path. If the `fastembed` model cannot load, memory operations fail loudly rather than silently degrading to FNV-1a pseudo-vectors. See [ADR-EMB-001](../../../docs/adr/ADR-EMB-001-neural-embeddings-mandatory.md).
+**Model:** `fast-all-MiniLM-L6-v2` via `fastembed` (Qdrant's ONNX client). 384-dim, L2-normalized vectors. ~3 s for 1000 entries.
 
-### The Embedding Alignment Problem
+**Mandatory.** Hash-based fallback was removed (ADR-EMB-001) — if `fastembed` cannot load, memory operations fail loudly rather than silently degrading. Model auto-downloads to `~/.cache/fastembed` on first use; for offline / sandboxed runs pre-populate the cache or set `FASTEMBED_CACHE`.
 
-**Critical rule:** Query embeddings MUST match stored embeddings. Computing cosine similarity between vectors from different models produces meaningless scores.
+**Legacy aliases.** Entries embedded by earlier moflo versions may be tagged `Xenova/all-MiniLM-L6-v2` or `onnx`. They share the same vector space and are treated as compatible at search time (`semantic-search.mjs` `COMPATIBLE_MODELS`).
 
-Both the search scripts and the MCP memory tools use `fastembed` for query vectors and filter stored entries by `embedding_model` (via the legacy-compatible alias list above), so a mixed-version database remains coherent.
+**Embedding alignment is critical.** Query embeddings MUST match stored embeddings — cosine similarity across model families produces meaningless scores. Both the search scripts and the MCP memory tools use `fastembed` for queries and filter stored entries by `embedding_model`.
 
 ---
 
 ## RAG Indexing Pipeline
 
-### How `index-guidance.mjs` Works
+`index-guidance.mjs`:
 
-1. **Scan** configured directories for `.md` files
-2. **Hash check** — Skip files whose content hash hasn't changed (unless `--force`)
-3. **Store full document** as `doc-{prefix}-{name}` (for complete retrieval)
-4. **Chunk on `##` headers** — Each H2 section becomes a separate entry
-5. **H3 subsections** become child chunks with parent H2 as context prefix
-6. **Force-split** sections over 4000 chars on paragraph boundaries
-7. **Build RAG metadata** for every chunk:
+1. Scan configured directories for `.md` files
+2. Hash check — skip files whose content hash hasn't changed (`--force` overrides)
+3. Store the full document as `doc-{prefix}-{name}` for complete retrieval
+4. Chunk on `##` headers — each H2 becomes a separate entry
+5. H3 subsections become child chunks with the parent H2 as context prefix
+6. Force-split sections over 4000 chars on paragraph boundaries
+7. Build RAG metadata (`parentDoc`, `prevChunk`, `nextChunk`, `siblings`, `hierarchicalParent/Children`, `contextBefore/After`)
+8. Prepend 20% overlapping context from neighbors
+9. Stale-cleanup pass — drop entries for files no longer on disk
+10. Spawn `build-embeddings.mjs` to vectorize new entries
 
-| Metadata Field | Purpose |
-|---------------|---------|
-| `parentDoc` | Link back to full document |
-| `prevChunk` / `nextChunk` | Sequential navigation |
-| `siblings` | All chunk keys from same document |
-| `hierarchicalParent` / `hierarchicalChildren` | H2->H3 relationships |
-| `contextBefore` / `contextAfter` | 20% overlapping text from adjacent chunks |
-
-8. **Prepend context** — Each chunk's searchable content includes overlap from neighbors
-9. **Stale cleanup** — After indexing, remove entries for files that no longer exist on disk
-10. **Background embedding** — Spawn `build-embeddings.mjs` to generate vectors
-
-### Configuring Indexed Directories
-
-In `moflo.yaml`:
+**Configuration in `moflo.yaml`:**
 
 ```yaml
 guidance:
@@ -165,80 +76,62 @@ guidance:
     - docs/guides
 ```
 
-Default directories (when no config): `.claude/guidance`, `docs/guides`
-
-Moflo also automatically indexes its own bundled guidance from `node_modules/moflo/.claude/guidance/` when installed as a dependency.
+Default (when no config): `.claude/guidance`, `docs/guides`. Moflo also auto-indexes its own bundled guidance from `node_modules/moflo/.claude/guidance/` when installed as a dependency.
 
 ---
 
 ## Search Commands
 
-All methods auto-detect the stored embedding model and generate matching query vectors:
+All entry points auto-detect the stored model and generate matching query vectors.
 
-**MCP (Preferred):** `mcp__moflo__memory_search` — `query: "your query", namespace: "guidance"`
+**MCP (preferred):** `mcp__moflo__memory_search` — `query`, `namespace`, `limit`, `threshold`.
 
-**CLI (Fallback):**
+**CLI (fallback):**
 ```bash
-npx flo memory search --query "your query" --namespace guidance
+npx flo memory search --query "your query" --namespace guidance --limit 5 --threshold 0.3
 ```
 
-**Search options:**
-
-| Flag | Default | Purpose |
-|------|---------|---------|
-| `--namespace` | all | Filter to specific namespace |
-| `--limit` | 5 | Number of results |
-| `--threshold` | 0.3 | Minimum similarity score |
-| `--json` | false | Output as JSON |
+**Code map search.** When you need to find where a type, service, entity, or component lives, search `code-map` BEFORE Glob/Grep:
 
-### Code Map Search (for codebase navigation)
-
-When you need to find where a type, service, entity, or component lives — search `code-map` BEFORE using Glob/Grep:
-
-**MCP:** `mcp__moflo__memory_search` — `query: "payment service", namespace: "code-map"`
-
-**What code-map contains:**
-
-| Chunk prefix | What it answers |
-|--------------|-----------------|
+| Chunk prefix | Answers |
+|--------------|---------|
 | `project:` | "What's in the api project?" |
-| `dir:` | "What types are in the entities directory?" |
+| `dir:` | "What types are in entities/?" |
 | `iface-map:` | "What implements IPaymentService?" |
 | `type-index:` | "Where is Service defined?" |
 
+Use `mcp__moflo__memory_search` with `namespace: "code-map"`.
+
 ---
 
 ## Session Start Indexing
 
-On every session start, `hooks.mjs` spawns `index-all.mjs` which runs the full chain:
-
-| Indexer | Namespace | What it does |
-|---------|-----------|--------------|
-| `index-guidance.mjs` | `guidance` | Chunks markdown, builds RAG links |
-| `generate-code-map.mjs` | `code-map` | Scans source for types, interfaces, directories |
-| `index-tests.mjs` | `tests` | Indexes test structure |
-| `index-patterns.mjs` | `patterns` | Extracts per-file code patterns |
-| `build-embeddings.mjs` | all | Generates vectors for any unembedded entries |
+On every session start, `hooks.mjs` spawns `index-all.mjs`, which runs the full chain incrementally — files whose hash hasn't changed are skipped. Use `--force` to reindex everything.
 
-Indexing is incremental by default — files whose content hash hasn't changed are skipped. Use `--force` to reindex everything.
+| Indexer | Namespace |
+|---------|-----------|
+| `index-guidance.mjs` | `guidance` |
+| `generate-code-map.mjs` | `code-map` |
+| `index-tests.mjs` | `tests` |
+| `index-patterns.mjs` | `patterns` |
+| `build-embeddings.mjs` | (generates vectors for any unembedded entries) |
 
 ---
 
-## Replication Guide
+## Writing Guidance That Indexes Well
 
-To set up this system in a new project:
+Authoring rules — Purpose line, imperative voice, 5–30-line H2 sections, decision tables, no decorative headings, See Also block — live in `.claude/guidance/moflo-guidance-rules.md`. Follow that file when writing or editing any guidance.
 
-```bash
-npm install moflo
-npx flo init
-```
-
-Create `.claude/guidance/` with markdown files following the optimization rules above, then:
+The retrieval-specific rules below only apply to docs you want surfaced via `memory_search`:
 
-```bash
-npx flo-index --force                                              # Index documents
-npx flo memory search --query "your domain query" --namespace guidance  # Verify
-```
+| Signal | Why it matters |
+|--------|----------------|
+| `**Purpose:**` line after H1 | First chunk of every doc; primary relevance signal |
+| Domain-specific H2 headings (`## JWT Authentication Pattern`, not `## Pattern`) | Heading text is the chunk's embedding anchor |
+| 1000–4000 char H2 sections | Below 50 chars chunks are dropped; above 6000 chars get force-split mid-thought |
+| Self-contained H2 sections | Each chunk must answer a question without the surrounding doc |
+| Tables over prose for decisions | Structured data parses more reliably than paragraphs |
+| Cross-references in See Also | Builds the navigation graph (`prevChunk`/`nextChunk`/`siblings`) |
 
 ---
 
@@ -246,19 +139,20 @@ npx flo memory search --query "your domain query" --namespace guidance  # Verify
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| Search returns irrelevant results | Query/stored embedding model mismatch | Auto-detected now; verify with `--verbose` flag |
-| Low similarity scores | Query doesn't match domain terms | Include domain keywords in query |
-| "Vector: No" in list | Entry lacks embedding | Run `node bin/build-embeddings.mjs` |
-| Entries not found after adding file | Indexer hasn't run yet | Run `node bin/index-all.mjs` or restart session |
-| Bundled moflo guidance not indexed | Not installed as dependency | Only indexes when `node_modules/moflo/.claude/guidance/` exists |
-| Empty namespace | Indexer never ran or DB was purged | See `moflo-memorydb-maintenance.md` for reindex/purge procedures |
+| Search returns irrelevant results | Query/stored embedding model mismatch (legacy entry) | Auto-detected; verify with `npx flo-search --verbose` |
+| Low similarity scores | Query missing domain terms | Include domain keywords in the query |
+| `"Vector: No"` in `memory_list` | Entry lacks embedding | Run `node bin/build-embeddings.mjs` |
+| Entries not found after editing a file | Indexer hasn't run yet | Restart session or `node bin/index-all.mjs` |
+| Bundled moflo guidance not indexed | Running inside the moflo repo (same dir) | Bundled guidance only indexes when installed as a dependency |
+| Empty namespace | Indexer never ran or DB was purged | See `.claude/guidance/moflo-memorydb-maintenance.md` |
+| Embeddings fail offline | `fastembed` model cache missing | Pre-populate `~/.cache/fastembed` or set `FASTEMBED_CACHE` (see `docs/modules/embeddings.md`) |
 
 ---
 
 ## See Also
 
-- `moflo-memorydb-maintenance.md` — Database location, schema, purge/reindex procedures
-- `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
+- `.claude/guidance/moflo-memorydb-maintenance.md` — Database location, schema, purge/reindex procedures
+- `.claude/guidance/moflo-guidance-rules.md` — Universal authoring rules every guidance doc must follow
+- `.claude/guidance/moflo-subagents.md` — Memory-first subagent protocol that uses these search paths
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — Task & swarm coordination layered on top of memory
+- `.claude/guidance/moflo-core-guidance.md` — Full CLI/MCP reference and Auto-Learning protocol

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

@@ -6,10 +6,10 @@
 
 ## Database Location
 
-- **Path:** `.moflo/moflo.db` — canonical post-#727 location
+- **Path:** `.moflo/moflo.db` — canonical 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`).
+- **Legacy path:** `.swarm/memory.db` — older 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
 
@@ -109,7 +109,7 @@ 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 `moflo-session-start.md` § "Helper script sync").
+`hooks.mjs` spawns `index-all.mjs` on session start, which runs the full chain. The session-start launcher syncs the indexer scripts into `.claude/scripts/` on every version change so the chain always points at current code.
 
 ## Recovering From a Legacy DB
 
@@ -131,8 +131,6 @@ flo memory restore-learnings --from .swarm/memory.db.bak
 
 ## 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)
+- `.claude/guidance/moflo-memory-strategy.md` — When to use which namespace; semantic search query patterns
+- `.claude/guidance/moflo-core-guidance.md` — `flo memory` CLI subcommands and `flo doctor` output
+- `.claude/guidance/moflo-subagents.md` — Memory-first protocol that depends on these indexes being healthy

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

@@ -66,7 +66,7 @@ A rewrite rule looks like:
 
 ```ts
 {
-  name: '#879: record-memory-searched → gate-hook.mjs',
+  name: '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',
 }
@@ -100,25 +100,23 @@ Failures land on stderr and similarly surface to the agent. If something silentl
 | 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.
+Future versions may add hook-block-level locking to suppress drift detection wholesale.
 
 ---
 
 ## 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`).
+**"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, the rule name in the launcher source (`HOOK_REWRITE_RULES`) describes what each fix does.
 
 **"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.
+**"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 — `gate-hook.mjs` is the wrapper that adds prompt-submit reset behavior; `gate.cjs` direct calls bypass it.
 
-**"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.
+**"I want to inspect what would be rewritten without actually changing my settings."** — The current launcher applies rewrites on every start. A manual dry-run mode is planned but not yet exposed.
 
 ---
 
 ## 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).
+- `.claude/guidance/moflo-core-guidance.md` — Session-start cost expectations and what the launcher syncs into `.claude/`.
+- `.claude/guidance/moflo-cross-platform.md` — Why hook commands always use `node "$CLAUDE_PROJECT_DIR/..."` paths.

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

@@ -20,14 +20,14 @@
 
 ## Single Source Tree Under `src/cli/`
 
-**The entire moflo source lives at `src/cli/`** after the workspace-collapse epic ([#586](https://github.com/eric-cielo/moflo/issues/586) / [ADR-0001](../../docs/adr/0001-collapse-moflo-workspace-packages.md)). There is no longer a `src/modules/<pkg>/` workspace tree, no per-package `tsconfig.json`/`package.json`, and no `@moflo/<pkg>` workspace-package specifiers.
+**The entire moflo source lives at `src/cli/`** after the workspace-collapse refactor (ADR-0001). There is no longer a `src/modules/<pkg>/` workspace tree, no per-package `tsconfig.json`/`package.json`, and no `@moflo/<pkg>` workspace-package specifiers.
 
 | Pattern | Status |
 |---------|--------|
 | `import { Foo } from '../bar.js'` | CORRECT — same-tree relative import |
 | `import { Foo } from '@moflo/neural'` | WRONG — that workspace package no longer exists |
 | `import { Foo } from '../../../../modules/<pkg>/...'` | WRONG — fixed-depth pre-collapse paths (banned by ESLint per [feedback_no_fixed_depth_paths.md](../../docs/adr/0001-collapse-moflo-workspace-packages.md)) |
-| `import { Foo } from 'src/modules/...'` | WRONG — that tree was deleted in #602 |
+| `import { Foo } from 'src/modules/...'` | WRONG — that tree was deleted during the workspace collapse |
 
 The drift guard at `src/cli/__tests__/services/published-package-drift-guard.test.ts` enforces that no `@moflo/*` bare specifiers reappear in source.
 
@@ -70,13 +70,13 @@ Compiled output is generated by `npm run build` (single `tsc` run from repo root
 
 ## Async-Eligible Operations Must Be Async By Default
 
-**Use the async API for any operation that has one, unless a documented reason forces sync.** Sync IO and busy-waits block the event loop — on a hot path that pins a CPU core, stalls timers, and turns a "best-effort" failure into a hang. Issue #854 burned 5s of CPU to a `while (Date.now() < end)` busy-wait inside an already-async launcher.
+**Use the async API for any operation that has one, unless a documented reason forces sync.** Sync IO and busy-waits block the event loop — on a hot path that pins a CPU core, stalls timers, and turns a "best-effort" failure into a hang. A representative incident burned ~5s of CPU per session to a `while (Date.now() < end)` busy-wait that had been pasted into an already-async launcher.
 
 | Operation | Use | Avoid |
 |-----------|-----|-------|
 | File IO inside an `async` function | `fs/promises` (`readFile`, `copyFile`, `mkdir`) | `*Sync` variants |
 | Delays | `await new Promise(r => setTimeout(r, ms))` | `while (Date.now() < end)` busy-wait |
-| Spawning long-running children | `await new Promise` around `spawn`/`execFile` | `execFileSync`/`spawnSync` (Windows timeouts orphan children — #744) |
+| Spawning long-running children | `await new Promise` around `spawn`/`execFile` | `execFileSync`/`spawnSync` (on Windows, timeouts orphan child processes) |
 
 **Sync is OK only when:** the function cannot be `async` (top-level config reader before any await; certain CommonJS hooks); the IO is microscopic on a known-fast path (one `existsSync` probe, one tiny `readFileSync`); or conversion churn outweighs the benefit. Document the reason in a one-line comment.
 
@@ -98,6 +98,6 @@ Before creating any new source file, verify:
 ## See Also
 
 - `CLAUDE.md` — Project-wide rules, consumer project checklist
-- `.claude/guidance/shipped/moflo-guidance-rules.md` — Rules for writing guidance docs
+- `.claude/guidance/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-connectors.md

@@ -16,7 +16,7 @@
 
 **Do NOT create a connector for each external service.** Instead, compose the built-in connectors in spell steps. A Slack integration is an `http` connector call with the Slack API URL and token — not a `slack` connector.
 
-This design was established in issues #233–#259: the original per-service connector approach (Slack, OneDrive, Gmail, Google Drive — #234–#237) was superseded by generalized wrappers with capability enforcement (#254, #257, #258, #259).
+This design replaced an earlier per-service connector approach (Slack, OneDrive, Gmail, Google Drive) with generalized wrappers backed by capability enforcement.
 
 ---
 
@@ -128,6 +128,5 @@ If you do need one:
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — CapabilityGateway and enforcement rules
-- `.claude/guidance/shipped/moflo-spell-engine.md` — Running spells, step command types
-- `.claude/guidance/shipped/moflo-spell-engine-architecture.md` — Architecture decisions
+- `.claude/guidance/moflo-spell-sandboxing.md` — CapabilityGateway and enforcement rules
+- `.claude/guidance/moflo-spell-engine.md` — Running spells, step command types

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

@@ -120,7 +120,6 @@ const runner = createRunner({
 
 ## 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
+- `.claude/guidance/moflo-spell-engine.md` — Built-in step types, spell definition format, runner lifecycle, error codes
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability declarations a custom step must include and how the sandbox enforces them
+- `.claude/guidance/moflo-spell-connectors.md` — When to write a connector instead of a custom step (resource-shaped vs. action-shaped extension)