moflo 4.10.11 → 4.10.13

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

@@ -176,6 +176,21 @@ Checks: Node version (20+), Git, config validity, daemon status, memory database
 
 ---
 
+## Monorepo Layout
+
+**Purpose:** prevent the most common moflo misconfig — daemon islands in monorepos (#1174).
+
+| Rule | Why |
+|------|-----|
+| One `.moflo/` per monorepo, at the repo root | The daemon, MCP server, and CLI all walk up from `cwd` to locate state. Two `.moflo/` directories under one tree means two daemons with separate sockets, ports, and registries — the MCP server bound to one will not see tools/state from the other. |
+| Never run `flo init` inside a sub-workspace of an existing moflo project | `flo init` refuses by default when an ancestor `.moflo/moflo.db` is detected. `--force` overrides if you genuinely want isolated state. |
+| `flo doctor` flags every nested `.moflo/` it finds | Component name: `nested-moflo`. Status warns when any island exists. |
+| `flo doctor --fix -c nested-moflo` archives each nested directory | Renames `<sub>/.moflo` → `<sub>/.moflo-archived-<ISO>` (never deletes). Manual review path: archived directories stay on disk. |
+
+The resolver (`findProjectRoot`) prefers the topmost ancestor with `.moflo/moflo.db` so every cwd in the tree agrees on the canonical anchor. If `CLAUDE_PROJECT_DIR` is set explicitly, it overrides this — only use that override when you intend isolated state.
+
+---
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
@@ -188,6 +203,7 @@ Checks: Node version (20+), Git, config validity, daemon status, memory database
 | 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 the moflo repo | Bundled guidance only indexes when installed as a dependency in a different project |
+| `mcp__moflo__*` tools missing in monorepo session | Nested `.moflo/` directories spawned separate daemons (#1174) | Run `flo doctor -c nested-moflo`; if any are found, `flo doctor --fix -c nested-moflo` archives them. Restart Claude Code to reconnect. |
 
 See `.claude/guidance/moflo-memory-strategy.md` for memory-specific troubleshooting and `.claude/guidance/moflo-spell-troubleshooting.md` for spell sandbox/network failures.
 

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

@@ -1,34 +1,194 @@
-# MoFlo Memory Protocol — Search, Traverse, Retrieve
+# MoFlo Memory Protocol — Pick Namespace, Query, Traverse
 
-**Purpose:** How to use moflo's chunked memory effectively. Search returns navigable chunks — traverse the chunk graph, do not bulk-retrieve every hit.
+**Purpose:** How to use moflo's chunked memory effectively. Memory indexes far more than user-feedback narratives: per-directory symbol tables, test-to-source reverse indexes, RAG-chunked guidance docs, code patterns, and incident learnings. Querying the wrong namespace — or asking the wrong shape of question — wastes the gate-enforced first search. Pick the namespace, pivot on the symbol, read the similarity score, traverse via neighbors.
+
+## Rule (MUST)
+
+When a search hit carries a non-null `navigation` field, you MUST traverse via `mcp__moflo__memory_get_neighbors` — NOT bulk-retrieve every hit with `memory_retrieve`. The `navigation` crumb is the chunking architecture's contract; bulk-retrieving every search hit defeats it and is a protocol violation. Use `memory_retrieve` only for a single specific key you already hold, or for non-chunk entries where `navigation` is null.
 
 ---
 
-## Rule (MUST)
+## What's Actually in Each Namespace
+
+The moflo index is large and dense. Sizing as of 2026-05-16 on the moflo repo (similar shape in any consumer project after first indexing pass):
+
+| Namespace | Entries | What's indexed | Use for |
+|-----------|---------|----------------|---------|
+| `code-map` | ~1,400 | Per-directory symbol tables (`dir:src/cli/services` lists ~430 symbols → defining files), per-file type/function summaries | "where is X defined", "what's in directory Y", "what types live in file Z" |
+| `guidance` | ~1,000 | RAG-chunked `.claude/guidance/**/*.md` — every chunk has nav crumbs (parent doc, prev/next/siblings) | Project rules, decision context, "how should I…" docs |
+| `patterns` | ~970 | Per-file pattern entries, aggregate stats ("middleware: 16 occurrences"), narrative fix-patterns (`pattern:swarm-dir-recreation-fix-1168`) | "what's our pattern for X", recurring fix shapes, conventions |
+| `tests` | ~850 | `test-file:` entries per test, plus `test-map:<production path>` reverse-index ("2 test files cover this") | "what tests cover module X", test inventory, coverage gaps |
+| `learnings` | grows over time | Incident narratives keyed by issue/PR (`1145-daemon-port-collision-fix`) | Error → fix recall, "did we hit this before", post-mortems |
+
+`code-map` and `tests` are auto-indexed from the source tree. `guidance` is auto-indexed from `.claude/guidance/**`. `patterns` mixes auto-mined heuristics with narratives stored via `memory_store`. `learnings` is curated — store with `mcp__moflo__memory_store` when you finish a non-trivial debug.
+
+---
+
+## Worked Examples — Real Queries Against the Live Store
+
+Each example shows the query, namespace, top hit, similarity score, and why memory wins over the alternative.
+
+### Example 1 — "Where is symbol X defined" → `code-map`
+
+```
+mcp__moflo__memory_search {
+  query: "where is BashSafetyHook defined",
+  namespace: "code-map"
+}
+```
+
+Top hits:
+
+```
+file:src/cli/shared/hooks/safety/bash-safety.ts        similarity 0.86
+dir:src/cli/shared/hooks/safety                        similarity 0.82
+```
+
+**Wins over Grep.** Grep returns every mention of the identifier across the tree; `code-map` returns the defining file plus the sibling-symbol context (the dir entry lists all 18 types in that directory) in one call.
+
+### Example 2 — "Tests for module Y" → `tests`
+
+```
+mcp__moflo__memory_search {
+  query: "tests for daemon port collision",
+  namespace: "tests"
+}
+```
+
+Top hits:
+
+```
+test-file:src/cli/__tests__/commands/daemon-port-resolution.test.ts   similarity 0.79
+test-map:src/cli/commands/daemon                                       similarity 0.75
+```
+
+**Wins over Glob + Read.** The `test-map:` reverse-index answers "what tests cover this production path" directly — no need to Glob for filename matches and Read each candidate to confirm coverage.
+
+### Example 3 — "Patterns for X" → `patterns`
+
+```
+mcp__moflo__memory_search {
+  query: "vitest mocking patterns for middleware",
+  namespace: "patterns"
+}
+```
+
+Top hits:
+
+```
+pattern-import-module-e9oqfm        similarity 0.87
+pattern-test-mocking-76mtme         similarity 0.81
+pattern-api-middleware-q9gk50       similarity 0.78
+```
+
+**Competitive with Grep + multiple Reads.** Returns conceptual hits without needing to know file paths or naming conventions.
 
-When a search hit carries a non-null `navigation`, you MUST call `mcp__moflo__memory_get_neighbors` to traverse — not `mcp__moflo__memory_retrieve`. `memory_retrieve` is for fetching one specific chunk in full, or for non-chunk entries where `navigation` is null. Bulk-retrieving search hits defeats the chunking architecture.
+### Example 4 — "How does feature work" → `guidance`
 
-## Decision Table
+```
+mcp__moflo__memory_search {
+  query: "how should subagents handle the memory search gate",
+  namespace: "guidance"
+}
+```
+
+Top hits — four chunks across four different docs, all 0.86+:
+
+```
+chunk-skill-eldar-2                                  (parent: doc-skill-eldar)
+chunk-guidance-upgrade-contract-6                    (parent: doc-guidance-upgrade-contract)
+chunk-guidance-memory-traversal-architecture-5       (parent: doc-guidance-memory-traversal-architecture)
+chunk-guidance-moflo-subagents-0                     (parent: doc-guidance-moflo-subagents)
+```
+
+**Wins over Read.** Semantic recall across docs without knowing filenames. Each hit carries a `navigation` object — traverse to siblings/prev/next for adjacent context.
+
+### Example 5 — "Did we hit this error before" → `learnings`
+
+```
+mcp__moflo__memory_search {
+  query: "daemon port collision fix",
+  namespace: "learnings"
+}
+```
+
+Hits a curated incident narrative (e.g. `1145-daemon-port-collision-fix`) with the prior diagnosis + fix shape. **Wins over searching closed GitHub issues** — the narrative is the distilled fix, not the raw discussion.
+
+---
+
+## Querying Technique — Five Rules for High-Signal Searches
+
+Five rules that turn ceremonial searches into high-signal ones. Each one fixes a real failure mode observed in long sessions.
+
+| Rule | Why |
+|------|-----|
+| **Pivot on the symbol.** Include the bare identifier (`BashSafetyHook`, `findProjectRoot`) verbatim in the query | Embedding similarity is much higher on the literal token than on a natural-language paraphrase |
+| **Always specify `namespace`** when you know the answer shape | Cross-namespace results dilute relevance — a `tests` query without namespace pulls noisy `code-map` and `patterns` hits |
+| **Read the `similarity` score** | `≥ 0.80` is a confident hit; `0.60–0.79` is tangential; `< 0.60` is noise. Re-query with a sharper symbol/keyword rather than acting on weak hits |
+| **Traverse, don't re-search** | When a chunk hit has `navigation`, use `mcp__moflo__memory_get_neighbors` for adjacent context — one round-trip, no re-embedding cost |
+| **Don't bulk-retrieve search hits** | `memory_retrieve` is for one specific key you already hold. Calling it for every search hit defeats the chunking architecture |
+
+### Query shape — do / don't
+
+| Don't | Do |
+|-------|-----|
+| `memory_search { query: "where is the bash safety hook implemented in the project" }` | `memory_search { query: "BashSafetyHook", namespace: "code-map" }` |
+| `memory_search { query: "find all tests for daemon stuff" }` | `memory_search { query: "daemon port collision", namespace: "tests" }` |
+| `memory_search { query: "how do I do mocks" }` (no namespace, vague) | `memory_search { query: "vitest mocking middleware", namespace: "patterns" }` |
+| `memory_retrieve` on each of 5 search hits | `memory_get_neighbors { key: <best hit>, include: ['prev','next','siblings'] }` |
+
+---
+
+## Tool Selection — Memory API
+
+Once you have a search hit, pick the right follow-up call by what you need next. Bulk-retrieving every search hit is a protocol violation; the table below maps each follow-up shape to its single correct tool.
 
 | You want | Use | Why |
 |----------|-----|-----|
-| Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with compact `navigation` (parentDoc, prev/next, chunkTitle) |
-| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, returns shaped entries with full nav |
+| Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with `navigation` (parentDoc, prev/next, chunkTitle) |
+| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, shaped entries with full nav |
 | Same-section peers (h2/h3 family) | `memory_get_neighbors` `{ include: ['siblings'] }` or `['parent','children']` | Hierarchical traversal — cheaper than re-searching |
-| Full content of one chunk | `mcp__moflo__memory_retrieve` `{ key }` | Returns full nav object for further traversal |
+| Full content of one specific chunk | `mcp__moflo__memory_retrieve` `{ key }` | For a key you already hold — never for bulk-retrieving search hits |
 | Whole source doc when truly needed | `Read` `parentPath` from any chunk's nav | Disk read is cheaper than re-indexed `doc-*` |
 
-## Anti-Patterns
+---
+
+## Tool Selection — Memory vs. Filesystem Tools
+
+Pick memory when the question is about indexed knowledge (symbols, tests, patterns, docs, incidents); pick filesystem/git when the question is about *current authoritative state* the index can't guarantee fresher than disk.
+
+| Question shape | First call |
+|----------------|-----------|
+| "Where is symbol X defined" | `memory_search` namespace `code-map` (pivot on bare symbol) |
+| "What tests cover module Y" | `memory_search` namespace `tests` |
+| "What's our pattern for Z" | `memory_search` namespace `patterns` |
+| "How / why / project rule for W" | `memory_search` namespace `guidance` |
+| "Did we hit error V before" | `memory_search` namespace `learnings` |
+| "Find files matching glob `**/*.test.ts`" | `Glob` — file-system metadata, not indexed content |
+| "What's in the working tree right now / what did I just edit" | `Read` — memory is a snapshot, working-tree is authoritative |
+| "What's in this commit / git history" | `git log` / `git diff` |
+
+The first five rows pivot through memory because the index already knows the answer. The last three pivot through filesystem/git because they ask about *current authoritative state*, which memory cannot guarantee fresher than disk.
+
+---
+
+## Anti-Patterns — Common Memory Query Mistakes
+
+These six failure modes account for almost every "memory returned noise" complaint. Each row pairs the antipattern with the corrective shape from the cheat sheet above.
 
 | Don't | Do instead |
 |-------|-----------|
+| Search memory without a namespace, get noise, fall back to Grep | Specify the namespace that matches the question shape (table above) |
 | Retrieve every search hit blindly | Traverse via `memory_get_neighbors` when `navigation` is present — bulk `memory_retrieve` per hit is a protocol violation |
 | Open the source file when a chunk would do | Stay in the chunk graph; `Read` `parentPath` only for the rare full-doc case |
 | Search again for a key you already have | `memory_retrieve` or `memory_get_neighbors` directly |
+| Phrase queries as natural-language questions | Pivot on the bare symbol or keyword — embedding similarity is higher on the literal token |
+| Act on a hit with similarity < 0.6 | Re-query with a sharper symbol/keyword; weak hits are noise, not signal |
 
 ---
 
 ## See Also
 
-- `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — namespaces, query examples, MCP-first tool selection
-- `.claude/guidance/moflo-memory-strategy.md` — How chunking, embeddings, and the RAG index work
+- `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — gate enforcement, namespace selection rules
+- `.claude/guidance/moflo-memory-strategy.md` — How chunking, embeddings, and the RAG index work under the hood
+- `.claude/guidance/moflo-memorydb-maintenance.md` — How the underlying memory DB is kept healthy (indexing, vacuum, integrity)

package/.claude/helpers/gate.cjs

@@ -81,7 +81,21 @@ var config = loadGateConfig();
 var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
-var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
+// #1171 — DANGEROUS gained PowerShell additions to match the matcher widening
+// that now routes the dedicated `PowerShell` tool through check-dangerous-command.
+// POSIX entries still apply because PS will execute them when invoked. Substring
+// match (case-insensitive) inside the gate.
+var DANGEROUS = [
+  'rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda',
+  // PowerShell destructive patterns. Won't catch every adversarial spelling
+  // (PS aliases let `ri -r -force C:\` mean the same thing) but covers the
+  // common-typo destruction class — symmetric to the POSIX list's intent.
+  'remove-item -recurse -force c:\\',
+  'remove-item -recurse -force /',
+  'remove-item -recurse -force ~',
+  'format-volume',
+  'clear-disk',
+];
 
 // #1132 — Bash memory-first gate.
 //
@@ -94,6 +108,9 @@ var CREDIT_MEMORY_SEARCH_RE = /semantic-search|memory search|memory retrieve|mem
 // check-before-scan gates by going through the shell. Anchored to the start of
 // the line so subcommands inside pipelines or `npm install grep` don't trip.
 // Covers POSIX read/search tools, Windows cmd `type`, and PowerShell readers.
+// #1171 — extended with PowerShell-native exploration forms now that the matcher
+// widens to the `PowerShell` tool. Plain `Get-ChildItem` without -Recurse stays
+// uncovered (it's `ls`-equivalent and plain `ls` is allowed).
 var READ_LIKE_BASH_RE = new RegExp([
   '^\\s*(?:cat|head|tail|less|more|bat|xxd|od|hexdump)\\b',
   '^\\s*(?:grep|rg|ag|fgrep|egrep|find|fd)\\b',
@@ -108,6 +125,17 @@ var READ_LIKE_BASH_RE = new RegExp([
   // primary risk pattern is leaking past the gate via `type src\foo.ts`.
   '^\\s*type\\s+\\S*[\\\\/.]',
   '^\\s*(?:Get-Content|gc|Select-String|sls)\\b',
+  // #1171 — PowerShell recursive exploration (parallel to POSIX `find`/`fd`).
+  // The `-Recurse` flag is what makes it expensive enough to gate; plain
+  // `Get-ChildItem` is `ls`-shaped and intentionally not blocked.
+  '^\\s*(?:Get-ChildItem|gci)\\b[^|]*-Recurse\\b',
+  // #1171 — cmd-style recursive listing (`dir /s` or `dir /S`). Only the
+  // Windows `/s` form, NOT POSIX `dir -s` (sort-by-size, where `dir` is aliased
+  // to `ls -l` on many distros) — false-positive blocking that would break
+  // legitimate POSIX listings.
+  '^\\s*dir\\b[^|]*\\s\\/[sS]\\b',
+  // #1171 — PowerShell hex dump, parallel to POSIX `xxd`/`hexdump`.
+  '^\\s*Format-Hex\\b',
 ].join('|'), 'i');
 // CARVE-OUT: commands that LOOK read-like but are operational. Anchored to the
 // LEADING command — the pipe-filter case (`npm test | grep FAIL`) is already
@@ -129,6 +157,32 @@ var BASH_CARVE_OUT_RE = new RegExp([
   // `find` commands that lack a `-delete` / `-exec rm` suffix.
   '^\\s*find\\s+.+?-(delete|exec\\s+rm)\\b',
 ].join('|'));
+// #1171 follow-up — strip quoted string bodies and heredoc bodies from a shell
+// command for purposes of dangerous-pattern substring matching. Used by
+// check-dangerous-command. Does NOT strip $(...) or `...` because those bodies
+// execute. Double-quoted strings handle escaped quotes (`\"`) correctly so
+// `git commit -m "fix \"X\""` strips the whole quoted body, not just the first
+// `\"` pair. Single quotes don't have escapes in bash/sh — `'[^']*'` is exact.
+function stripQuotedAndHeredocs(cmd) {
+  var out = cmd;
+  // Heredoc tail: `<<TOKEN`, `<<-TOKEN`, `<<'TOKEN'`, `<<"TOKEN"` through end-of-input.
+  // Bash heredocs are multi-line; in single-line tool inputs they show up as the
+  // tail after `<<TOKEN`. Conservative tail-strip — benign content after a heredoc
+  // body on the same logical line is also stripped, harmless for this gate.
+  // Token class includes `-` so hyphenated heredoc tags (`<<END-OF-DOC`) match
+  // the full token, not just the leading word — without this the strip would
+  // halt at `<<END` and leave `-OF-DOC` plus the body as literal text.
+  out = out.replace(/<<-?\s*['"]?[\w-]+['"]?[\s\S]*$/, '');
+  // Here-string `<<<word` — strip the word.
+  out = out.replace(/<<<\s*\S+/g, '');
+  // Single-quoted strings — no escapes inside single quotes in sh/bash.
+  out = out.replace(/'[^']*'/g, "''");
+  // Double-quoted strings — `(?:[^"\\]|\\.)*` matches anything except an
+  // unescaped `"`, so escaped `\"` mid-string doesn't terminate the strip early.
+  out = out.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  return out;
+}
+
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
 
@@ -254,14 +308,27 @@ var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|t)(
 // Edits to these don't change runtime behaviour, so they don't invalidate prior test/simplify runs.
 // Lock files and .gitignore are tracked but inert; package.json/*.yaml ARE source — they reset.
 var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^|[\\\/])(CHANGELOG(?:\.md)?|\.env\.example|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/i;
+// #1176 — path-based inert markers. The extension-based RE above can't cover
+// `.github/workflows/*.yml` without also exempting `moflo.yaml` / `tsconfig.yaml`
+// (which ARE source). Anchor on the GitHub-meta directories that hold CI config
+// and template scaffolds — editing those doesn't expose new runtime surface, so
+// they shouldn't reset testsRun/simplifyRun the way a real source edit does.
+// Trailing terminator includes `.` so the single-file template form
+// `.github/PULL_REQUEST_TEMPLATE.md` matches alongside the directory form.
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)/i;
 // Test files: invalidate the testing gate (tests are stale once test code changes)
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
 var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|spec|specs|cypress|e2e|fixtures?)[\\\/]|\.(test|spec)\.[mc]?[jt]sx?$|\.fixture\.[mc]?[jt]sx?$/i;
+// #1176 — source-file extensions used by the no-source-files PR exemption.
+// When the cumulative branch diff has zero files matching this RE (i.e. only
+// YAML/MD/JSON/lockfiles/images/templates), the testing/simplify/learnings
+// gates auto-pass at `check-before-pr`. Lists every language moflo ships
+// against — additions here should match TEST_RUNNER_RE's language coverage.
+var SOURCE_FILE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|sh|bash|ps1)$/i;
 // Docs-only PR exemption: text/markup/image extensions that cannot change runtime behaviour.
-// If EVERY file in the PR diff matches this, skip testing/simplify/learnings gates.
-// Anchored to end-of-path so e.g. `foo.md.js` does not match. Excludes lock files / configs
-// on purpose — those are inert for edit-reset (above) but not "documentation".
+// Retained for the transparency message when the diff is *purely* docs (no YAML/JSON either)
+// — gives a more specific reason than "no source files" in that subset.
 var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
 
 // Classifier-aware simplify gate skip. Returns a string reason if the gate
@@ -285,13 +352,24 @@ function classifyForGateSkip(state) {
   } catch (e) { return null; }
   if (typeof classify !== 'function') return null;
 
-  function tryClassify(diffText, label) {
+  function tryClassify(diffText, label, allowSmallReviewFix) {
     try {
       var dec = classify(diffText);
       if (dec.tier === 'TRIVIAL') {
         var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
         return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
       }
+      // #1176 — SMALL review-fix shape (snapshot path only). A ≤30-LOC delta with
+      // zero new declarations on top of an already-reviewed branch is the typical
+      // "apply 3 review fixes" cycle — re-running /flo-simplify against the same
+      // surface plus a few-line tweak adds no new signal. Baseline path stays
+      // TRIVIAL-only so brand-new SMALL features still get reviewed.
+      if (allowSmallReviewFix && dec.tier === 'SMALL') {
+        var totalLoc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        if (totalLoc <= 30 && (dec.stats.declAdded || 0) === 0) {
+          return label + ' is SMALL review-fix shape (' + totalLoc + ' LOC, no new declarations)';
+        }
+      }
     } catch (e) { /* fall through */ }
     return null;
   }
@@ -311,7 +389,9 @@ function classifyForGateSkip(state) {
     var workTreeA = gitDiff(['diff', 'HEAD']) || '';
     if (snapDiff !== null) {
       var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
-      var hit = tryClassify(combined, 'delta since last /simplify');
+      // Snapshot path: allow SMALL review-fix shape because the original /simplify
+      // already covered the surface and only tiny no-decl-touching tweaks followed.
+      var hit = tryClassify(combined, 'delta since last /simplify', true);
       if (hit) return hit;
     }
   }
@@ -475,6 +555,11 @@ switch (command) {
     // #1132 — preserve CREDIT side-effect AND add a BLOCK arm for read-like
     // Bash commands. Wired as PreToolUse[Bash] (was PostToolUse before #1132)
     // so process.exit(2) actually prevents the read from reaching the shell.
+    //
+    // #1171 — the case name is historical. The matcher now also covers the
+    // dedicated `PowerShell` tool, and READ_LIKE_BASH_RE already matched PS
+    // readers (Get-Content/Select-String/Get-ChildItem -Recurse/Format-Hex).
+    // Treat this case as shell-agnostic read-gate logic.
     var cmd = process.env.TOOL_INPUT_command || '';
 
     // 1) CREDIT — preserved behavior. A real memory-search invocation flips
@@ -531,6 +616,15 @@ switch (command) {
         s.testsRun = true;
         writeState(s);
       }
+    } else if (cmd) {
+      // #1176 — emit a stderr crumb when invoked with a non-empty command that
+      // doesn't match the test-runner pattern. Common pitfall: users run the
+      // stamp manually from a terminal to "satisfy the gate"; the silent no-op
+      // looks indistinguishable from success. gate-hook.mjs drops stderr from
+      // exit-0 invocations, so this only surfaces to direct CLI use — exactly
+      // the case where the friction lives.
+      var preview = cmd.length > 80 ? cmd.slice(0, 77) + '...' : cmd;
+      process.stderr.write('gate: record-test-run no-op — TOOL_INPUT_command="' + preview + '" did not match TEST_RUNNER_RE\n');
     }
     break;
   }
@@ -551,13 +645,21 @@ switch (command) {
         if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
       } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
       if (changed) writeState(s);
+    } else if (skName) {
+      // #1176 — same rationale as record-test-run. A no-op stamp on a non-simplify
+      // skill name is silent to hooks (gate-hook.mjs drops exit-0 stderr) but
+      // visible when a user runs the stamp directly to "satisfy the gate" and
+      // wonders why simplifyRun stays false.
+      process.stderr.write('gate: record-skill-run no-op — TOOL_INPUT_skill="' + skName + '" is not simplify/flo-simplify\n');
     }
     break;
   }
   case 'reset-edit-gates': {
     var fp = process.env.TOOL_INPUT_file_path || '';
-    // Inert files (markdown, lockfiles, CHANGELOG, .env.example): no gate reset.
-    if (fp && EDIT_RESET_SKIP_BOTH_RE.test(fp)) break;
+    // Inert files (markdown, lockfiles, CHANGELOG, .env.example) AND inert paths
+    // (.github/workflows/, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE/, #1176):
+    // no gate reset — editing these doesn't expose new runtime surface.
+    if (fp && (EDIT_RESET_SKIP_BOTH_RE.test(fp) || EDIT_RESET_SKIP_PATH_RE.test(fp))) break;
     var s = readState();
     // Test-only edits invalidate testsRun but preserve simplifyRun (#908).
     var isTestOnly = fp && EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE.test(fp);
@@ -580,14 +682,27 @@ switch (command) {
     // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
     var cmd = process.env.TOOL_INPUT_command || '';
     if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
-    // Docs-only exemption: if every file changed vs the merge-base is a docs/image
-    // file (no runtime-behaviour surface), skip the testing/simplify/learnings gates
+    // No-source-files exemption (#1176, supersedes the original docs-only path).
+    // If every file changed vs the merge-base is either a docs/image file or a
+    // path-inert file (.github/workflows/, ISSUE_TEMPLATE/, PULL_REQUEST_TEMPLATE/)
+    // — i.e. NO source files in the diff — skip testing/simplify/learnings gates
     // and surface a one-line transparency note. Falls through to the standard gate
     // on any failure (no base, no diff, exec error) — fail-safe by design.
+    //
+    // Source-file detection is the inverse of the inert checks: a file is "source"
+    // when it matches SOURCE_FILE_RE AND is not inside an inert path. This catches
+    // `.github/workflows/foo.sh` (sh extension but path-inert → no source).
     var changed = getChangedFilesVsBase();
-    if (changed && changed.length > 0 && changed.every(function(f) { return DOCS_ONLY_RE.test(f); })) {
-      process.stdout.write('Docs-only PR (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
-      break;
+    if (changed && changed.length > 0) {
+      var hasSource = changed.some(function(f) {
+        return SOURCE_FILE_RE.test(f) && !EDIT_RESET_SKIP_PATH_RE.test(f);
+      });
+      if (!hasSource) {
+        var allDocs = changed.every(function(f) { return DOCS_ONLY_RE.test(f); });
+        var reason = allDocs ? 'Docs-only' : 'No source files in branch diff';
+        process.stdout.write(reason + ' (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
+        break;
+      }
     }
     var s = readState();
     // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
@@ -620,7 +735,17 @@ switch (command) {
     process.exit(2);
   }
   case 'check-dangerous-command': {
-    var cmd = (process.env.TOOL_INPUT_command || '').toLowerCase();
+    // #1171 follow-up — strip quoted string bodies and heredoc bodies before
+    // substring-matching DANGEROUS. Without this, `git commit -m "...remove-item
+    // -recurse -force c:\..."` blocks because the literal pattern appears in
+    // the quoted message body. Quoted text isn't executing — the gate's job is
+    // to catch typo-class destruction in the actual command, not text mentions
+    // inside arguments. Trade-off: `bash -c "rm -rf /"` also bypasses now; the
+    // gate is a typo safety net, not a security boundary, so this is acceptable.
+    // Command substitutions `$(...)` and backticks are NOT stripped — those
+    // bodies execute and dangerous content there is real.
+    var raw = process.env.TOOL_INPUT_command || '';
+    var cmd = stripQuotedAndHeredocs(raw).toLowerCase();
     for (var i = 0; i < DANGEROUS.length; i++) {
       if (cmd.indexOf(DANGEROUS[i]) >= 0) {
         console.log('[BLOCKED] Dangerous command: ' + DANGEROUS[i]);

package/.claude/skills/publish/SKILL.md

@@ -25,9 +25,9 @@ Automated release pipeline for moflo. Bumps version, commits, builds, tests, run
 
 ## --check / -ch flag (presence-only)
 
-**Default (flag absent):** runs build + doctor + trigger-based manual checks only. Skips lint/test/smoke because those gates are covered by CI on every PR + push to main (`ci.yml`, `consumer-install-smoke.yml`).
+**Default (flag absent):** runs build + doctor + trigger-based manual checks only. Skips local lint/test/smoke because lint+test are covered by `ci.yml` on every PR + push to main, and **cross-platform smoke is dispatched as part of this skill** (Step 8.5 below) — the `release-smoke.yml` workflow runs the full 3-OS matrix on the exact commit about to be published.
 
-**With `--check` or `-ch` (any presence):** runs the full pre-flight from `pre-publish-rules.md` — lint, build, test, doctor (strict), clean smoke, populated smoke, and a forced full walk of every manual gate. Use this for publishes that didn't go through a green PR, risky releases, or when you want belt-and-suspenders.
+**With `--check` or `-ch` (any presence):** runs the full pre-flight from `pre-publish-rules.md` — lint, build, test, doctor (strict), local clean smoke, local populated smoke, and a forced full walk of every manual gate. Use this for publishes that didn't go through a green PR, risky releases, or when you want belt-and-suspenders on the local box in addition to the CI matrix.
 
 The flag is presence-only. `--check` and `-ch` both set it to true. There is no `--check=true` / `--check=false` syntax — absence means false.
 
@@ -103,14 +103,14 @@ Doctor is the only check with no CI equivalent — it inspects local state (daem
 
 **Never `--fix` on the publish path.** A release pipeline must fail fast on broken local state, not silently repair it; a doctor that auto-repairs masks the very signal we want — "something is off, stop and investigate before shipping." If `doctor --strict` fails, stop and run `flo healer --fix` (or `npx moflo doctor --fix`) interactively, verify the repair, then retry the publish.
 
-### Step 6: Smoke Tests (only if `CHECK_MODE=true`)
+### Step 6: Local Smoke Tests (only if `CHECK_MODE=true`)
 
 ```bash
 npm run test:smoke
 npm run test:smoke:populated
 ```
 
-Skipped by default — `consumer-install-smoke.yml` runs both profiles on Ubuntu/macOS/Windows on every PR + push to main. Run when `--check` is set.
+Skipped by default. Local smoke covers the same harness as CI's Ubuntu leg, so it adds little signal over `release-smoke.yml`'s Ubuntu matrix entry (Step 8.5). Run only when `--check` is set — useful if you want belt-and-suspenders on the local box before dispatching the full CI matrix.
 
 ### Step 7: Manual Gate Walk (trigger-based, even in default mode)
 
@@ -144,6 +144,42 @@ git push origin main
 
 Only commit version-related files. Do not stage unrelated changes.
 
+### Step 8.5: Dispatch release-smoke and block until green
+
+```bash
+# Capture the SHA we just pushed — release-smoke runs against this exact commit.
+PUBLISH_SHA=$(git rev-parse HEAD)
+
+# Trigger the full 3-OS × 2-harness matrix. `sha` is a required workflow input
+# so the dispatched run is unambiguously bound to this commit.
+gh workflow run release-smoke.yml --ref main -f sha="$PUBLISH_SHA"
+
+# Give GitHub a moment to register the dispatched run.
+sleep 10
+
+# Find the run we just dispatched by matching head_sha. This is robust against
+# concurrent dispatches (e.g. a manual UI retry from another tab) — never use
+# `--limit 1` alone, which would race against any unrelated in-flight run.
+RUN_ID=$(gh run list --workflow=release-smoke.yml --branch main \
+  --json databaseId,headSha \
+  --jq ".[] | select(.headSha == \"$PUBLISH_SHA\") | .databaseId" \
+  | head -1)
+
+if [ -z "$RUN_ID" ]; then
+  echo "ERROR: no release-smoke run found for SHA $PUBLISH_SHA. Wait a few seconds and retry, or check https://github.com/eric-cielo/moflo/actions/workflows/release-smoke.yml" >&2
+  exit 1
+fi
+
+# Block until the run completes. Exits non-zero on failure.
+gh run watch "$RUN_ID" --exit-status
+```
+
+`release-smoke.yml` runs full consumer + populated smoke on Ubuntu/macOS/Windows, plus file-sync smoke on all three filesystems. Per-PR CI is intentionally Ubuntu-only to keep recurring cost manageable — the full cross-platform matrix is paid once here, at publish time, against the exact commit we're about to publish.
+
+**Wall time expectations**: typical run is ~15-20 min once caches are warm. **The first dispatch after `release-smoke.yml` lands will have cold caches on every leg** (no prior runs of this workflow exist to populate the `consumer-warm` and `fastembed` caches per-OS). Expect ~25-35 min on that first dispatch — the macOS leg is the long pole. Subsequent dispatches reuse the cache and settle to the typical ~15 min.
+
+**If `gh run watch` exits non-zero**: stop immediately. Inspect the failed leg with `gh run view "$RUN_ID" --log-failed`, fix the underlying issue, push the fix, then re-run this step (no need to rerun Steps 0–8 — the bump commit is already on main, and the SHA-filtered lookup will pick up the new dispatched run against the same SHA only after `cancel-in-progress: false` lets the previous run drain). Do not proceed to `npm publish` until release-smoke is green for the SHA you intend to publish.
+
 ### Step 9: Verify npm Authentication
 
 ```bash
@@ -223,8 +259,8 @@ Build:           passed
 Tests:           skipped (CI-covered) | <N> files passed, <N> tests passed
 Lint:            skipped (CI-covered) | passed
 Doctor:          <N> passed, <N> warnings
-Smoke (clean):   skipped (CI-covered) | passed
-Smoke (popl):    skipped (CI-covered) | passed
+Smoke (local):   skipped (CI-covered) | passed
+Release-smoke:   green (run <id>, 3-OS × 2-harness)
 Triggered gates: <list> | none
 Published:       moflo@<new-version>
 Installed:       moflo@<new-version> (devDependency)
@@ -257,5 +293,7 @@ For the common case — publishing right after a merged green PR — the default
 - `docs/BUILD.md` — Step-by-step build/publish process this skill mirrors
 - `.claude/guidance/internal/dogfooding.md` — Why we catch consumer-facing regressions first as our own dependency
 - `harness/consumer-smoke/README.md` — Smoke harness profiles (clean + populated) that prove a consumer install works
-- `.github/workflows/ci.yml` — Lint/build/test gates this skill skips by default
-- `.github/workflows/consumer-install-smoke.yml` — Smoke gates this skill skips by default
+- `.github/workflows/ci.yml` — Lint/build/test gates this skill skips by default (ubuntu-only)
+- `.github/workflows/consumer-install-smoke.yml` — Per-PR ubuntu-only smoke
+- `.github/workflows/file-sync-smoke.yml` — Per-PR ubuntu-only file-sync smoke
+- `.github/workflows/release-smoke.yml` — Full 3-OS × 2-harness matrix this skill dispatches at Step 8.5