moflo 4.9.15 → 4.9.17

package/.claude/guidance/shipped/moflo-epic-processing.md

@@ -4,7 +4,7 @@
 
 ---
 
-## Configuration (moflo.yaml)
+## moflo.yaml epic Section
 
 **Add an `epic` section to `moflo.yaml` to control epic behavior.** All settings have sensible defaults.
 

package/.claude/guidance/shipped/moflo-task-icons.md

@@ -41,7 +41,7 @@ description: "ICON [Role] Brief description"
 | performance-* | ⚡ | `⚡ [Perf] Profile query bottleneck` |
 | general-purpose | 🤖 | `🤖 [Agent] Execute multi-step task` |
 
-## Examples
+## Wrong vs Right Examples
 
 ### TaskCreate
 

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

@@ -90,9 +90,13 @@ 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
 
-Invoke `/guidance -a` via the `Skill` tool to run the structural audit. 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.
+**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.
+
+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.
+
+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:
 
@@ -153,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)
 
@@ -300,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

@@ -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/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.15';
+export const VERSION = '4.9.17';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.15",
+  "version": "4.9.17",
   "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.14",
+    "moflo": "^4.9.16",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"