moflo 4.9.14 → 4.9.16

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

@@ -307,3 +307,4 @@ See `moflo-memory-strategy.md` for memory-specific troubleshooting.
 - `.claude/guidance/shipped/moflo-session-start.md` — Complete session-start lifecycle (DB heal, sync, migrations, daemon)
 - `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/` and how surgical self-heal works
 - `.claude/guidance/shipped/moflo-cross-platform.md` — Windows/macOS/Linux portability rules for any code change
+- `.claude/guidance/shipped/moflo-verbose-command-filtering.md` — Filter long verbose commands at the source; never tee-then-grep

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

@@ -0,0 +1,45 @@
+# Verbose Command Filtering — Filter at Source, Never Tee-Then-Read
+
+**Purpose:** Pipe long verbose commands (smoke runs, full test suites, builds with `--verbose`) through a filter at execution time so only relevant lines reach the model context. Never tee output to disk and `tail`/`grep` it later — every follow-up read re-loads the full file into context (~5K tokens per round-trip).
+
+---
+
+## The Rule
+
+| Pattern | Verdict |
+|---------|---------|
+| `cmd 2>&1 \| grep -E "FAIL\|Summary"` (run_in_background) | ✅ Filter at source |
+| `cmd 2>&1 \| tee .tmp.log` then later `tail`/`grep` `.tmp.log` | ❌ Tee-then-read |
+
+Tee-then-read is the silent context killer. The Bash tool surfaces stdout into context, so each follow-up `grep`/`tail` of a tee'd file re-reads the file fresh on every call. Three follow-ups burn 15K+ tokens before any decision lands. Filtering at source emits the matching lines once.
+
+## When to Apply
+
+Smoke harness runs, full `vitest`/`jest` suites, builds with `--verbose`, anything passing `--trace`, any `node ... --verbose` invocation. If you genuinely need the full log for post-mortem, write it to disk but inspect it OUTSIDE the model loop (have the user open it, attach it to an issue) — do NOT pipe a tee'd file back through Bash.
+
+## Concrete Examples
+
+```bash
+# ✅ Smoke harness
+node harness/consumer-smoke/run.mjs 2>&1 | grep -E "FAIL|Summary|Zombie"
+# ❌ node harness/consumer-smoke/run.mjs 2>&1 | tee .tmp.log; tail .tmp.log
+
+# ✅ Vitest full suite
+npm test -- --reporter=verbose 2>&1 | grep -E "FAIL|✗|Error:"
+# ❌ npm test 2>&1 | tee .test.log; grep FAIL .test.log
+
+# ✅ Build with verbose
+npm run build -- --verbose 2>&1 | grep -E "error TS|Failed|Cannot find"
+# ❌ npm run build 2>&1 | tee .build.log; grep "error TS" .build.log
+```
+
+## Why It Matters
+
+Case study: issue #903 burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline

package/.claude/helpers/simplify-classify.cjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * /simplify diff classifier — issue #908.
+ *
+ * Decides which review tier the current diff warrants and returns a JSON
+ * dispatch decision. The /simplify skill MUST call this first so routing is
+ * deterministic and unit-testable instead of a prose decision Claude makes
+ * over and over per run.
+ *
+ * Rule (per user direction): default to single-agent Sonnet review. Only
+ * escalate to a 3-agent fan-out when diff signals genuinely warrant it.
+ * Opus is never selected — the existing skill already documents that.
+ *
+ * Outputs JSON:
+ *   {
+ *     "tier": "TRIVIAL" | "SMALL" | "NORMAL",
+ *     "model": "sonnet",
+ *     "agentCount": 0 | 1 | 3,
+ *     "reasoning": [string, ...],
+ *     "stats": { added, deleted, fileCount, declAdded, declRemoved, ... }
+ *   }
+ *
+ * Usage:
+ *   node bin/simplify-classify.cjs [--base main]
+ *   node bin/simplify-classify.cjs --diff <unified-diff-on-stdin>
+ *
+ * The --diff stdin form exists so unit tests can drive the classifier
+ * with synthetic diffs (no git repo required).
+ */
+'use strict';
+
+const { execSync } = require('child_process');
+
+// Paths where new logic warrants the 3-agent fan-out (issue #908).
+// Mechanical edits inside these paths are still SMALL; only adding/removing
+// declarations triggers escalation.
+const SECURITY_PATHS = [
+  /(?:^|[\\\/])aidefence[\\\/]/i,
+  /(?:^|[\\\/])swarm[\\\/]consensus[\\\/]/i,
+  /(?:^|[\\\/])hooks?[\\\/](?:handlers?|gate|wiring)/i,
+  /(?:^|[\\\/])services[\\\/]daemon-lock\.ts$/i,
+  /(?:^|[\\\/])bin[\\\/]gate\./i,
+  /(?:^|[\\\/])bin[\\\/]session-start-launcher\./i,
+  /(?:^|[\\\/])\.claude[\\\/]helpers[\\\/]gate/i,
+];
+
+function safeExec(cmd) {
+  try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }); }
+  catch { return ''; }
+}
+
+function readDiffFromGit(base) {
+  // Combined diff: committed-since-base + working-tree
+  const committed = safeExec(`git diff ${base}...HEAD`);
+  const working = safeExec('git diff HEAD');
+  return committed + (working ? '\n' + working : '');
+}
+
+/**
+ * Parse a unified-diff string into per-file stats and aggregate signals.
+ * No git/I/O — pure function over the diff text. Test-friendly.
+ */
+function parseDiff(diff) {
+  const lines = diff.split('\n');
+  const files = new Map(); // filename → { added, deleted, declAdded, declRemoved, isNew, isRenamed }
+  let current = null;
+
+  // Match function/class/export-const-arrow/method declarations being
+  // added or removed. Conservative — biased toward false negatives so we
+  // don't over-escalate.
+  const DECL_RE = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type)\s+\w/;
+  const ARROW_DECL_RE = /^(?:export\s+)?(?:const|let|var)\s+\w+\s*[:=].*=>\s*\{?$/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+
+    // File header: `diff --git a/path b/path`
+    let m = ln.match(/^diff --git (?:a\/)?(.+?) (?:b\/)?(.+)$/);
+    if (m) {
+      const filename = m[2];
+      current = { filename, added: 0, deleted: 0, declAdded: 0, declRemoved: 0, isNew: false, isRenamed: false };
+      files.set(filename, current);
+      continue;
+    }
+    if (!current) continue;
+
+    if (ln.startsWith('new file mode')) current.isNew = true;
+    if (ln.startsWith('rename from') || ln.startsWith('rename to') || ln.startsWith('similarity index')) current.isRenamed = true;
+
+    // Skip diff headers
+    if (ln.startsWith('+++') || ln.startsWith('---') || ln.startsWith('@@') || ln.startsWith('index ')) continue;
+
+    if (ln.startsWith('+') && !ln.startsWith('+++')) {
+      current.added++;
+      const body = ln.slice(1).trim();
+      if (DECL_RE.test(body) || ARROW_DECL_RE.test(body)) current.declAdded++;
+    } else if (ln.startsWith('-') && !ln.startsWith('---')) {
+      current.deleted++;
+      const body = ln.slice(1).trim();
+      if (DECL_RE.test(body) || ARROW_DECL_RE.test(body)) current.declRemoved++;
+    }
+  }
+
+  // Aggregate
+  let added = 0, deleted = 0, declAdded = 0, declRemoved = 0;
+  let newFiles = 0, renamedFiles = 0;
+  let securityHit = false;
+  for (const f of files.values()) {
+    added += f.added;
+    deleted += f.deleted;
+    declAdded += f.declAdded;
+    declRemoved += f.declRemoved;
+    if (f.isNew) newFiles++;
+    if (f.isRenamed) renamedFiles++;
+    if (SECURITY_PATHS.some(rx => rx.test(f.filename))) securityHit = true;
+  }
+
+  return {
+    added, deleted, declAdded, declRemoved,
+    netDecls: declAdded - declRemoved,
+    fileCount: files.size,
+    newFiles, renamedFiles,
+    securityHit,
+    files: [...files.keys()],
+  };
+}
+
+/**
+ * Pure decision function. Takes parsed stats, returns dispatch decision.
+ * No I/O. Easy to unit-test with synthetic stats.
+ */
+function decide(stats) {
+  const reasoning = [];
+  const totalChange = stats.added + stats.deleted;
+
+  if (totalChange === 0) {
+    return { tier: 'TRIVIAL', model: 'sonnet', agentCount: 0, reasoning: ['empty diff — nothing to review'], stats };
+  }
+
+  // TRIVIAL: tiny diff, no declarations changed
+  if (totalChange <= 10 && stats.fileCount <= 1 && stats.netDecls === 0 && stats.declAdded === 0 && stats.declRemoved === 0) {
+    reasoning.push(`≤10 LOC in 1 file with no declaration changes`);
+    return { tier: 'TRIVIAL', model: 'sonnet', agentCount: 0, reasoning, stats };
+  }
+
+  // Mechanical relocation detection — the #906 case.
+  // If declarations were both ADDED and REMOVED at roughly matching rates,
+  // it's a structural move, not net-new logic. Judge by declaration balance,
+  // not raw LOC balance — formatting/blank-line differences between source
+  // and destination files easily push raw LOC out of balance even when the
+  // semantic change is purely "moved 5 functions across 5 new files".
+  // Mechanical relocations are SMALL even when many files / many lines.
+  const declTouched = stats.declAdded + stats.declRemoved;
+  const isMostlyRelocation = stats.declAdded >= 2
+    && stats.declRemoved >= 2
+    && Math.abs(stats.netDecls) <= Math.max(2, Math.floor(declTouched * 0.30));
+
+  if (isMostlyRelocation) {
+    reasoning.push(
+      `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
+    );
+    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+  }
+
+  // Escalation triggers — any one trips NORMAL (3 agents).
+  // Always Sonnet — Opus is never the right model for /simplify per skill rule.
+  const triggers = [];
+  if (totalChange > 500) triggers.push(`>500 LOC changed (${totalChange})`);
+  if (stats.fileCount >= 5 && stats.netDecls >= 3) triggers.push(`${stats.fileCount} files with ${stats.netDecls} net new declarations`);
+  if (stats.securityHit && stats.netDecls > 0) triggers.push('security-sensitive path with new logic');
+  if (stats.newFiles >= 3 && stats.declAdded >= 5) triggers.push(`${stats.newFiles} new files with ${stats.declAdded} new declarations`);
+
+  if (triggers.length > 0) {
+    return { tier: 'NORMAL', model: 'sonnet', agentCount: 3, reasoning: triggers, stats };
+  }
+
+  // Default: SMALL — single sonnet agent
+  reasoning.push(`small/medium diff: ${totalChange} LOC across ${stats.fileCount} file(s), +${stats.declAdded}/-${stats.declRemoved} decls`);
+  return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+}
+
+function classifyDiff(diffText) {
+  return decide(parseDiff(diffText));
+}
+
+function classifyFromGit(base = 'main') {
+  return classifyDiff(readDiffFromGit(base));
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const baseIdx = args.indexOf('--base');
+  const base = baseIdx >= 0 ? args[baseIdx + 1] : 'main';
+  const stdinDiff = args.includes('--diff') || args.includes('--stdin');
+
+  let result;
+  if (stdinDiff) {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (d) => { buf += d; });
+    process.stdin.on('end', () => {
+      result = classifyDiff(buf);
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    });
+  } else {
+    result = classifyFromGit(base);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
+}
+
+module.exports = { parseDiff, decide, classifyDiff, classifyFromGit };

package/.claude/skills/eldar/SKILL.md

@@ -90,17 +90,24 @@ Count `.md` files under `.claude/guidance/` (recursive). Severity table:
 | 3–10 | info |
 | 11+ | info |
 
-### 1g. Guidance Structure (only if 1f found ≥1 file)
+### 1g. Guidance Structure — MANDATORY when guidance docs exist
 
-Apply the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md`. For each `.md` file, check:
+**This step is not optional.** If 1f found ≥1 guidance file, you MUST invoke `/guidance -a` via the `Skill` tool *inline, during this audit run, before rendering the report.* Do not defer it ("rerun separately if you want"), do not skip it because the corpus is large, do not substitute a hand-rolled grep pass — that defeats the single-source-of-truth contract.
 
-- Has `**Purpose:**` line right after H1
-- Has `## See Also` at end
-- Under 500 lines
-- H2 headings are specific (not "Overview", "Configuration", "Examples")
-- No hedged language in rule contexts (`should`, `might`, `consider`)
+The /guidance skill enforces the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md` (Purpose lines, See Also, generic H2s, hedged language, 500-line cap, RAG chunking) and is the single source of truth for those checks — never re-implement them here.
 
-Do **not** duplicate `/guidance -a`'s logic verbatim — just produce a one-line summary per file (`<file>: <N issues>`). The Eldar surface gaps; `/guidance -a` does the deep audit.
+If `/guidance -a` is genuinely too expensive (50+ files AND user explicitly asks for a fast read), skip it only after asking and surface the skip explicitly in the report (`Guidance structure | skipped at user request | warn`). Default behaviour is always to run it.
+
+Fold the result into the Eldar report under the "Guidance structure" row:
+
+| Outcome of `/guidance -a` | Eldar row severity |
+|---------------------------|--------------------|
+| 0 files with issues       | ok                 |
+| 1–2 files with issues     | info               |
+| 3+ files with issues      | warn               |
+| `/guidance` itself errors | warn — quote the error verbatim so the user can fix the offending file before re-running |
+
+When the user is in `--fix` mode and chooses guidance fixes from the triage menu (3b), the same /guidance skill is the handoff target — so the audit and the fix flow share one implementation.
 
 ### 1h. Memory Health
 
@@ -150,21 +157,13 @@ Glob — { pattern: ".claude/agents/**/*.md" }
 
 Count the result. `info` if 0 (no project-specific subagents — user is relying entirely on built-ins).
 
-### 1m. Stack → Guidance Cross-Reference (highest leverage)
-
-Detect the project's stack from manifests:
+### 1m. Stack → Guidance Cross-Reference (delegated to /guidance)
 
-| Manifest | Detected stack |
-|----------|----------------|
-| `package.json` deps | Node — inspect for React, Next, Drizzle, Prisma, Express, NestJS, Vite, etc. |
-| `pyproject.toml` / `requirements.txt` | Python — Django, FastAPI, SQLAlchemy, etc. |
-| `Cargo.toml` | Rust — axum, tokio, sqlx, etc. |
-| `go.mod` | Go — gin, sqlc, gorm, etc. |
-| `Gemfile` | Ruby — Rails, Sidekiq, etc. |
+Gap analysis (which codebase concerns lack a guidance doc) is the **/guidance skill's** responsibility — step 3b of `/guidance -a`. Since 1g already runs `/guidance -a` inline, do **not** re-implement gap detection here. Instead, fold the gap findings from /guidance's output into the Eldar report under the same "Stack → guidance" category.
 
-For each detected technology, check whether `.claude/guidance/` mentions it (Grep for the technology name across the directory). Each `(detected stack item, no guidance match)` pair becomes one `info` finding: "uses Drizzle ORM but no DB-conventions guidance — high-leverage gap".
+Each gap finding from /guidance becomes one row in the Eldar report. Severity carries through from /guidance (warn/info per its severity table).
 
-This is the **highest-impact finding** for new adopters. Lead with it in the recommendation.
+**Why delegated:** keeping a single source of truth — /guidance owns both the structural rule audit and the gap analysis, /eldar surfaces the results in its broader project audit. If /eldar duplicated gap detection, the two would drift.
 
 ### 1n. Anti-Pattern from History (best-effort, optional)
 
@@ -204,7 +203,9 @@ TOP 3 RECOMMENDATIONS
 2. Add Drizzle conventions guidance (info — high leverage)
    You use Drizzle ORM but have no DB-conventions doc. This is the
    single highest-leverage gap for getting Claude to write idiomatic
-   queries and migrations in your codebase.
+   queries and migrations in your codebase. /guidance -a (run inline
+   in step 1g) flagged 3 existing docs with structural issues; pick
+   one to fix alongside this new one.
    See: .claude/guidance/shipped/moflo-guidance-rules.md
 
 3. Run `flo healer --fix` (warn)
@@ -295,6 +296,7 @@ Never leave the user without a clear next step.
 - **Portable only.** This skill ships to consumers via `.claude/skills/**/*.md` in the package files array. Never assume moflo source paths or moflo-internal state.
 - **No kitchen sink.** The audit checklist is locked at the categories above. New checks require a specific portable benefit and an issue to discuss them.
 - **Read-only by default.** `/eldar` (no flag) never writes. Only `--fix` writes, and only with per-finding confirmation.
+- **Step 1g is mandatory, not optional.** Whenever `.claude/guidance/` has at least one file, `/guidance -a` runs inline as part of every audit. Saying "rerun /guidance -a separately if you want a structural pass" is a defect, not a feature — the user already asked for the structural pass by typing /eldar.
 - **Hand off to specialists.** `/guidance` for guidance authoring, `flo healer --fix` for setup repair, `flo init --upgrade` for wiring. The Eldar route, they don't reimplement.
 
 ## See Also

package/.claude/skills/guidance/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: guidance
 description: Add, edit, or audit guidance docs in this project's .claude/guidance/ directory following moflo's universal guidance rules. Default mode walks the user through one doc (creating or improving it); the -a flag audits every doc in the directory and offers per-file improvements.
-arguments: "[-a] [<topic-or-path>]"
+arguments: "[-a] <topic-or-path>"
 ---
 
 # /guidance — Author and audit project guidance
@@ -15,7 +15,7 @@ Help the user write, edit, or audit guidance files in their `.claude/guidance/`
 | Mode | Trigger | What it does |
 |------|---------|--------------|
 | Single-doc | no flag, optional `<topic-or-path>` arg | Walk the user through creating one new doc OR improving one existing doc |
-| Audit | `-a` flag | Scan every `.md` in `.claude/guidance/` (recursively), score each against the rules, present a triage report, then offer to fix per-file or in batch |
+| Audit | `-a` flag | Two passes over `.claude/guidance/`: (1) **structural audit** scoring each existing doc against the universal rules, (2) **gap analysis** scanning the codebase to identify high-leverage topics that *should* have a guidance doc but don't. Both feed one combined triage report. |
 
 ## Step 0 — Memory First
 
@@ -101,7 +101,11 @@ Then propose edits as concrete diffs — never rewrite the whole file unless the
 
 ## Step 3 — Audit Mode (`-a`)
 
-When `-a` is passed, scan the guidance directory and produce a triage report. Walk the directory yourself with `Glob` and `Read`; do not delegate to a subagent for the audit itself unless the user has 30+ files.
+Audit mode runs **two passes**, then merges them into one triage report. Both passes are mandatory — never skip one to save tokens. The user typed `-a` because they want both signals.
+
+### 3a. Structural audit (existing-doc rule conformance)
+
+Scan the guidance directory and score each `.md` against the universal rules. Walk the directory yourself with `Glob` and `Read`; do not delegate to a subagent for the audit itself unless the user has 30+ files.
 
 For each `.md` file:
 
@@ -112,11 +116,49 @@ For each `.md` file:
 5. Look for hedged language: `\b(should|might|consider|may want to)\b` in rule contexts
 6. Detect prose preambles (>3 paragraphs between H1 and first H2 rule)
 
-Render the report as a sortable table with one row per file, columns: file, lines, has-purpose, has-see-also, generic-headings count, hedged count. Highlight the worst offenders first.
+Render a sortable table with one row per file, columns: file, lines, has-purpose, has-see-also, generic-headings count, hedged count. Highlight the worst offenders first.
+
+**Note on `**Purpose:**` and `## See Also` regex:** ripgrep / Grep tool treats `**` as a glob escape and may return zero matches even when the markers are present. Use a plain string check (`Select-String` on Windows, `grep -F` elsewhere) or read the file and string-match in JS — never trust a zero count from a wildcard-ambiguous pattern without spot-checking one file.
+
+### 3b. Gap analysis (what topics are missing)
+
+Now look at *what isn't there*. Scan the codebase for high-leverage areas that lack a corresponding guidance doc, so Claude has nothing to follow when working in those areas.
+
+**Detection sources** (read each that exists):
+
+| Signal | What to learn |
+|--------|---------------|
+| `package.json` deps + devDeps | Frameworks/libraries the project relies on (React, Drizzle, Vitest, etc.) |
+| `pyproject.toml` / `requirements.txt` / `Cargo.toml` / `go.mod` / `Gemfile` | Same idea, other ecosystems |
+| Top-level source layout (`src/**`, `bin/**`, `scripts/**`, etc.) | Architectural concerns (e.g. a `daemon/` directory implies daemon architecture is a concern) |
+| `.claude/helpers/`, `.claude/scripts/`, `.claude/hooks/` | Hook + helper authoring is in scope |
+| MCP tool source (`mcp-tools/**`, `mcp-server/**`) | MCP tool authoring |
+| Test directories | Testing conventions (load-bearing if specific patterns exist — e.g. golden-file tests, snapshot conventions) |
+| `.github/workflows/` | CI/CD conventions |
+| Recent `git log` for files repeatedly edited together | Cross-cutting concerns that need explicit guidance |
+
+**Cross-reference:** for each detected concern, grep the existing `.claude/guidance/` corpus for keyword coverage. A topic is a **gap** if (a) the concern shows up in code (not just transitive deps) and (b) no existing guidance doc names it in the title or first H2.
+
+**Severity table:**
+
+| Concern type | Severity if unmatched |
+|--------------|------------------------|
+| Direct dep used pervasively (>10 files import it) | warn |
+| Architectural directory with >5 files | warn |
+| Direct dep used in 1–10 files | info |
+| Helper/hook/MCP authoring surface with custom code | warn |
+| CI/CD workflows beyond the standard ones | info |
+| Cross-cutting concern from git-history co-change | info |
+
+**Render gaps as a separate table** with columns: detected concern, evidence (file count or representative path), suggested doc filename, severity. Lead with the warns.
+
+**Don't auto-write any new doc.** Surface the gap, name the concern, propose a filename — then ask the user which gaps (if any) they want to fill. The single-doc mode (Step 2) handles authoring once they pick.
+
+### 3c. Combined triage and fixes
 
-After the table, list the **top 3–5 priority fixes** in plain English (not table format). For each, explain WHY (rule citation) and propose either a per-file fix or a batch fix.
+After both 3a and 3b, list the **top 3–5 priority items** across both passes in plain English. Mix them — a structural fix to an existing doc and a missing-doc gap can both make the top list. For each, explain WHY (rule citation for structural; concern + evidence for gaps) and propose either a per-file fix (3a) or a per-doc authoring flow (3b).
 
-Ask the user which to apply, then walk through the chosen fixes one at a time. **Never apply audit fixes without explicit per-file confirmation** — guidance is high-leverage; silent edits are dangerous.
+Ask the user which to apply, then walk through chosen items one at a time. **Never apply audit fixes without explicit per-file confirmation** — guidance is high-leverage; silent edits are dangerous. **Never auto-create gap docs** — every new doc starts as a single-doc mode session with the user.
 
 ## Step 4 — After Editing
 

package/.claude/skills/spell-schedule/SKILL.md

@@ -5,7 +5,7 @@ description: |
   Use when the user wants to schedule, automate, or recurringly run one of THEIR spells locally —
   e.g. "schedule the oap spell every hour", "run my audit spell every weekday at 9am", "fire X once tomorrow morning".
   This is the LOCAL daemon path. For remote Anthropic-cloud agents, use /schedule instead.
-arguments: "[spell-name-or-alias]"
+arguments: "<spell-name-or-alias>"
 ---
 
 # /spell-schedule — Schedule a Local Spell

package/dist/src/cli/commands/doctor-checks-deep.js

@@ -432,6 +432,31 @@ const REQUIRED_GATE_CASES = [
 // session-start-launcher.mjs in consumer projects without transitive failures.
 import { REQUIRED_HOOK_WIRING } from '../services/hook-wiring.js';
 export { REQUIRED_HOOK_WIRING };
+/**
+ * Detect "expected pre-publish drift" — source `bin/gate.cjs` is ahead of the
+ * installed `node_modules/moflo/bin/gate.cjs`, but the deployed
+ * `.claude/helpers/gate.cjs` still matches the installed version. This is the
+ * steady state in the moflo dogfood repo while a PR has landed but no
+ * `npm install moflo@<new>` has rotated the package.
+ *
+ * Returns true only when both are true:
+ *   - helper content equals installed bin content (helper is correctly synced
+ *     to what's installed)
+ *   - installed bin content differs from source bin content (source is ahead)
+ *
+ * If `node_modules/moflo/bin/gate.cjs` is missing (consumer never installed
+ * moflo, or path is unusual) we conservatively return false so other drift
+ * detection still applies.
+ */
+export function isExpectedPrePublishDrift(installedBinGate, helperContent, sourceBinContent) {
+    try {
+        const installedContent = readFileSync(installedBinGate, 'utf8');
+        return installedContent === helperContent && installedContent !== sourceBinContent;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Verify gate infrastructure health:
  * 1. gate.cjs exists and contains all required cases
@@ -474,14 +499,27 @@ export async function checkGateHealth() {
         issues.push(`gate.cjs missing cases: ${missingCases.join(', ')}`);
     }
     // 2. Check bin/gate.cjs sync
+    //
+    // The launcher syncs `node_modules/moflo/bin/gate.cjs` → `.claude/helpers/gate.cjs`
+    // on version change. Source `bin/gate.cjs` is only present in the moflo dogfood
+    // repo. During the dogfood publish window — between a PR landing and the next
+    // `npm install moflo@<new>` — source bin/ legitimately moves ahead of the
+    // installed bin/, while the helper continues to mirror the installed version.
+    // That's the expected steady state, not a bug; downgrade it to `warn` and skip
+    // the `fix` field so `--fix` doesn't paint a false success (#913).
     const binGate = join(projectDir, 'bin', 'gate.cjs');
+    const installedBinGate = join(projectDir, 'node_modules', 'moflo', 'bin', 'gate.cjs');
     if (existsSync(binGate)) {
         try {
             const binContent = readFileSync(binGate, 'utf8');
             if (binContent !== gateContent) {
-                // Check if it's a size difference (likely out of sync) vs whitespace
                 const sizeDiff = Math.abs(binContent.length - gateContent.length);
-                if (sizeDiff > 10) {
+                const prePublishDrift = isExpectedPrePublishDrift(installedBinGate, gateContent, binContent);
+                if (prePublishDrift) {
+                    warnings.push(`source bin/gate.cjs is ${sizeDiff} chars ahead of node_modules/moflo/bin/gate.cjs ` +
+                        '(expected pre-publish drift; resolves on next `npm install moflo@<new>`)');
+                }
+                else if (sizeDiff > 10) {
                     issues.push(`bin/gate.cjs out of sync with .claude/helpers/gate.cjs (${sizeDiff} chars differ)`);
                 }
                 else {

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.14';
+export const VERSION = '4.9.16';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.14",
+  "version": "4.9.16",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -81,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.13",
+    "moflo": "^4.9.15",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"