0.9.10

.gitignore

@@ -38,6 +38,7 @@ pytest-full.xml
 
 # Local agent-generated skills (keep canonical copies under docs/)
 .claude/
+.agents/
 /skills/
 CLAUDE.md
 AGENTS.md

RELEASE_NOTES_0.9.10.md

@@ -0,0 +1,127 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/peteromallet/desloppify/main/assets/mascot-no-bg.png" width="180" alt="Desloppify mascot">
+</p>
+
+This release adds **experimental Hermes Agent integration** for fully autonomous cleanup loops, **framework-aware detection** with a full Next.js spec, **SCSS language support**, significant **R language improvements**, and a **scan performance boost** from detector prefetch + caching — alongside a batch of bug fixes from the community.
+
+---
+
+**152 files changed | 54 commits | 5,466 tests passing**
+
+## Hermes Agent Integration (Experimental)
+
+We've been exploring what it looks like when a codebase health tool can actually *drive* an AI agent — not just generate reports, but orchestrate the entire cleanup loop autonomously. This release ships our first experimental integration with [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+The core idea: desloppify already knows what needs to be done (scan, triage, review, fix). Instead of printing instructions for a human, it can now tell the agent directly — switch to a cheap model for mechanical fixes, switch to an expensive one for architectural review, reset context between tasks, and keep the agent working via `/autoreply`, all without a human in the loop.
+
+What the integration enables:
+
+- **Autonomous review loops** — desloppify orchestrates blind reviews via `delegate_task` subagents (up to 3 concurrent), no human needed
+- **Model switching at phase boundaries** — cheap models for execution, expensive for planning/review, switched automatically
+- **Context management** — automatic resets between tasks to keep the agent focused on long sessions
+- **Lifecycle transitions** — desloppify tells Hermes what to do next via the Control API
+
+### How to try it
+
+**This requires the Control API branch of Hermes** ([NousResearch/hermes-agent#1508](https://github.com/NousResearch/hermes-agent/pull/1508)), which hasn't been merged upstream yet. Without it, Hermes works as a normal harness but can't do autonomous model switching or self-prompting.
+
+**Step 1 — Install Hermes from the Control API branch:**
+
+```bash
+git clone -b feat/control-api-autoreply https://github.com/peteromallet/hermes-agent.git
+cd hermes-agent
+pip install -e .
+```
+
+**Step 2 — Install desloppify and set up the Hermes skill doc:**
+
+```bash
+pip install desloppify[full]
+cd /path/to/your/project
+desloppify update-skill hermes
+```
+
+This writes a `AGENTS.md` skill document into your project that teaches Hermes how to use desloppify.
+
+**Step 3 — Start Hermes with the Control API enabled, pointed at your project:**
+
+```bash
+cd /path/to/your/project
+HERMES_CONTROL_API=1 hermes
+```
+
+**Step 4 — Tell it to scan.** In the Hermes session, type:
+
+```
+Run desloppify scan, then follow its coaching output to clean up the codebase.
+```
+
+Desloppify will guide Hermes through the full lifecycle — scanning, triaging findings, running blind reviews with subagents, and fixing issues. It switches models and resets context automatically at phase boundaries.
+
+**This is experimental and we're iterating fast.** We'd love feedback on the approach, rough edges, and what you'd want to see next. If you try it, please open an issue — every report helps.
+
+## Framework-Aware Detection
+
+Massive contribution from **@MacHatter1** (PR #414). A new `FrameworkSpec` abstraction layer for framework-specific detection, shipping with a full Next.js spec that understands App Router conventions, server components, `use client`/`use server` directives, and Next.js-specific lint rules. This means dramatically fewer false positives when scanning Next.js projects — framework idioms are recognized, not flagged. The spec system is extensible, so adding support for other frameworks (Remix, SvelteKit, etc.) is now a matter of writing a spec, not changing the engine.
+
+## SCSS Language Plugin
+
+Thanks to **@klausagnoletti** for adding SCSS/Sass support via stylelint integration (PR #428). Detects code smells, unused variables, and style issues in `.scss` and `.sass` files. @klausagnoletti has also submitted a follow-up PR (#452) with bug fixes, tests, and honest documentation — expected to land shortly after release.
+
+## Plugin Tests, Docs, and Ruby Improvements
+
+**@klausagnoletti** also contributed across multiple language plugins:
+
+- **Ruby plugin improvements** (PR #462) — expanded exclusions, detect markers (`Gemfile`, `Rakefile`, `.ruby-version`, `*.gemspec`), `default_src="lib"`, `spec/` + `test/` support, and 13 wiring tests. Also adds `external_test_dirs` and `test_file_extensions` params to the generic plugin framework.
+- **JavaScript plugin tests + README** (PR #458) — 12 sanity tests covering ESLint integration, command construction, fixer registration, and output parsing.
+- **Python plugin README** (PR #459) — user-facing documentation covering phases, requirements, and usage.
+
+## R Language Improvements
+
+**@sims1253** has been steadily building out R support and contributed four PRs to this release:
+
+- **Jarl linter** with autofix support (PR #425) — adds a fast R linter as an alternative to lintr
+- **Shell quote escaping fix** for lintr commands (PR #424) — prevents command injection on paths with special characters
+- **Tree-sitter query improvements** (PR #449) — captures anonymous functions in `lapply`/`sapply` calls and `pkg::fn` namespace imports
+- **Factory Droid harness support** (PR #451) — adds Droid as a new skill target, following the existing harness pattern exactly
+
+## Scan Performance: Detector Prefetch + Cache
+
+Another big one from **@MacHatter1** (PR #432). Cold and full scan times reduced significantly. Detectors now prefetch file contents and cache results across detection phases, avoiding redundant I/O. On large codebases this is a noticeable improvement.
+
+## Lifecycle & Triage
+
+- **Lifecycle transition messages** — the tool now tells agents what phase they're in and what to do next, with structured directives for each transition
+- **Unified triage pipeline** with step detail display
+- **Staged triage** now requires explicit decisions for auto-clusters before proceeding — no more accidentally skipping triage steps
+
+## Bug Fixes
+
+- **Binding-aware unused import detection for JS/TS** — @MacHatter1 (PR #433). No longer flags imports used via destructuring, `as` renames, or re-export patterns. This was a significant source of false positives in real JS/TS projects.
+- **Rust dep graph hangs** — @fluffypony (PR #429). String literals that look like import paths (e.g., `"path/to/thing"`) no longer cause the dependency graph builder to hang. @fluffypony also contributed Rust inline-test filtering (PR #440), which prevents `#[cfg(test)]` diagnostic noise from inflating production debt scores.
+- **Project root detection** (PR #439) — fixed cases where the project root was derived incorrectly, plus force-rescan now properly wipes stale plan data, and manual clusters are visible in triage.
+- **workflow::create-plan re-injection** — @cdunda-perchwell (PR #435). Resolved workflow items no longer reappear in the execution queue after reconciliation. @cdunda-perchwell also identified the related communicate-score cycle-boundary sentinel issue (#447, fix in PR #448).
+- **PHPStan parser fixes** — @nickperkins (PR #420). stderr output and malformed JSON from PHPStan no longer crash the parser. Clean, focused fix.
+- **Preserve plan_start_scores during force-rescan** — manual clusters are no longer wiped when force-rescanning.
+- **Import run project root** — `--scan-after-import` now derives the project root correctly from the state file path.
+- **Windows codex runner** (PR #453) — proper `cmd /c` argument quoting + UTF-8 log encoding for Windows. Reported by **@DenysAshikhin**.
+- **Scan after queue drain** (PR #454) — `score_display_mode` now returns LIVE when queue is empty, fixing the UX contradiction where `next` says "run scan" but scan refuses. Reported by **@kgelpes**.
+- **SKILL.md cleanup** (PR #455) — removes unsupported `allowed-tools` frontmatter, fixes batch naming inconsistency (`.raw.txt` not `.json`), adds pip fallback alongside uvx. Three issues all reported by **@willfrey**.
+- **Batch retry coverage gate** (PR #456) — partial retries now bypass the full-coverage requirement instead of being rejected. Reported by **@imetandy**.
+- **R anonymous function extraction** (PR #461) — the tree-sitter anonymous function pattern from PR #449 now actually works (extractor handles missing `@name` capture with `<anonymous>` fallback).
+
+## Community
+
+This release wouldn't exist without the community. Seriously — thank you all.
+
+**@MacHatter1** delivered three major PRs (framework-aware detection, detector prefetch + cache, binding-aware unused imports) that each individually would have been a headline feature. The framework spec system in particular opens up a whole new category of detection accuracy.
+
+**@fluffypony** contributed both the Rust dep graph hang fix and the inline-test filtering — the latter being 1,000+ lines of carefully tested Rust syntax parsing with conservative cfg predicate handling and thorough edge-case coverage.
+
+**@sims1253** has been the driving force behind R language support, with four PRs spanning linting, tree-sitter queries, and harness support. The R plugin is becoming genuinely useful thanks to this sustained effort.
+
+**@klausagnoletti** added SCSS support, improved the Ruby plugin, and contributed tests and documentation for JavaScript and Python plugins — seven PRs total (#428, #452, #457, #458, #459, #462). The kind of contributor who makes the codebase more trustworthy across the board.
+
+**@cdunda-perchwell** fixed two separate workflow re-injection bugs that were causing phantom plan items. **@nickperkins** shipped a clean PHPStan parser fix.
+
+Bug reporters **@willfrey**, **@DenysAshikhin**, **@kgelpes**, and **@imetandy** filed detailed, actionable issues that made fixes straightforward. Every one of those reports saved debugging time.

desloppify/app/cli_support/parser.py

@@ -10,6 +10,7 @@
     _add_backlog_parser,
     _add_config_parser,
     _add_detect_parser,
+    _add_directives_parser,
     _add_dev_parser,
     _add_exclude_parser,
     _add_autofix_parser,
@@ -139,6 +140,7 @@ def create_parser(*, langs: list[str], detector_names: list[str]) -> argparse.Ar
     # configure
     _add_zone_parser(sub)
     _add_config_parser(sub)
+    _add_directives_parser(sub)
     _add_langs_parser(sub)
     _add_dev_parser(sub)
     _add_update_skill_parser(sub)

desloppify/app/cli_support/parser_groups.py

@@ -7,6 +7,7 @@
 from desloppify.app.cli_support.parser_groups_admin import (  # noqa: F401 (re-exports)
     _add_config_parser,
     _add_detect_parser,
+    _add_directives_parser,
     _add_dev_parser,
     _add_autofix_parser,
     _add_langs_parser,
@@ -25,6 +26,7 @@
     "_add_backlog_parser",
     "_add_config_parser",
     "_add_detect_parser",
+    "_add_directives_parser",
     "_add_dev_parser",
     "_add_exclude_parser",
     "_add_autofix_parser",

desloppify/app/cli_support/parser_groups_admin.py

@@ -90,6 +90,17 @@ def _add_config_parser(sub) -> None:
     c_unset.add_argument("config_key", type=str, help="Config key name")
 
 
+def _add_directives_parser(sub) -> None:
+    p = sub.add_parser("directives", help="View/set agent directives for phase transitions")
+    d_sub = p.add_subparsers(dest="directives_action")
+    d_sub.add_parser("show", help="Show all configured directives")
+    d_set = d_sub.add_parser("set", help="Set a directive for a lifecycle phase")
+    d_set.add_argument("phase", type=str, help="Lifecycle phase name")
+    d_set.add_argument("message", type=str, help="Message to show at this transition")
+    d_unset = d_sub.add_parser("unset", help="Remove a directive for a lifecycle phase")
+    d_unset.add_argument("phase", type=str, help="Lifecycle phase name")
+
+
 def _fixer_help_lines(langs: list[str]) -> list[str]:
     fixer_help_lines: list[str] = []
     for lang_name in langs:
@@ -168,6 +179,8 @@ def _add_dev_parser(sub) -> None:
     )
     d_scaffold.set_defaults(wire_pyproject=True)
 
+    dev_sub.add_parser("test-hermes", help="Test Hermes model switching (switch and switch back)")
+
 
 def _add_langs_parser(sub) -> None:
     sub.add_parser("langs", help="List all available language plugins with depth and tools")
@@ -182,6 +195,6 @@ def _add_update_skill_parser(sub) -> None:
         "interface",
         nargs="?",
         default=None,
-        help="Agent interface (amp, claude, codex, cursor, copilot, windsurf, gemini, opencode). "
+        help="Agent interface (amp, claude, codex, cursor, copilot, windsurf, gemini, hermes, droid, opencode). "
         "Auto-detected on updates if omitted.",
     )

desloppify/app/commands/dev.py

@@ -23,6 +23,9 @@ def cmd_dev(args: argparse.Namespace) -> None:
         except ValueError as ex:
             raise CommandError(str(ex)) from ex
         return
+    if action == "test-hermes":
+        _cmd_test_hermes()
+        return
     raise CommandError("Unknown dev action. Use `desloppify dev scaffold-lang`.")
 
 
@@ -165,3 +168,54 @@ def _cmd_scaffold_lang(args: object) -> None:
             "  Next: implement real phases/commands/detectors and run pytest.", "dim"
         )
     )
+
+
+def _cmd_test_hermes() -> None:
+    """Test Hermes model switching — switch to a random model and back."""
+    import random
+    import time
+
+    from desloppify.app.commands.helpers.transition_messages import (
+        _hermes_available,
+        _hermes_get,
+        _hermes_send_message,
+    )
+
+    if not _hermes_available():
+        print(colorize('Hermes not enabled. Set "hermes_enabled": true in config.json', "yellow"))
+        return
+
+    # Get current model
+    info = _hermes_get("/sessions/_any")
+    if "error" in info:
+        print(colorize(f"Cannot reach Hermes: {info['error']}", "red"))
+        return
+
+    original_model = info.get("model", "unknown")
+    original_provider = info.get("provider", "unknown")
+    print(f"  Current model: {original_provider}:{original_model}")
+
+    # Pick a random test model
+    test_models = [
+        ("openrouter", "google/gemini-2.5-flash"),
+        ("openrouter", "meta-llama/llama-4-scout"),
+        ("openrouter", "mistralai/mistral-medium-3"),
+    ]
+    test_provider, test_model = random.choice(test_models)
+
+    # Switch to test model
+    print(f"  Switching to: {test_provider}:{test_model}")
+    result = _hermes_send_message(f"/model {test_provider}:{test_model}", mode="queue")
+    if not result.get("success"):
+        print(colorize(f"  Switch failed: {result.get('error', '?')}", "red"))
+        return
+    print(colorize("  ✓ Switch command sent", "green"))
+
+    # Wait a moment, then switch back
+    time.sleep(2)
+    print(f"  Switching back to: {original_provider}:{original_model}")
+    result = _hermes_send_message(f"/model {original_provider}:{original_model}", mode="queue")
+    if not result.get("success"):
+        print(colorize(f"  Switch-back failed: {result.get('error', '?')}", "red"))
+        return
+    print(colorize("  ✓ Restored original model", "green"))