---
name: GuruRMM project state — dev principles, webhook docs guard, pending setup
description: GuruRMM project state — dev principles (every feature full-stack: backend+API+UI+docs+scalability; product works without AI; FEATURE_ROADMAP update is part of definition-of-done), the webhook docs-only build guard (SPEC-020 Phase 0; repo copy of webhook-handler.py is STALE — don't redeploy), and the still-pending Mac install-hooks.sh setup on Mikes-MacBook-Air.
type: project
---

Rules: [[feedback_gururmm]]. Technical reference: [[reference_gururmm]]. Canonical principles doc: `projects/msp-tools/guru-rmm/docs/DESIGN.md` (this file is the in-context summary).

---

## Dev principles (created 2026-04-29; authority: Mike Swanson)

### Holistic feature development (MANDATORY)

Every GuruRMM feature ships with the complete stack:
1. **Backend / agent logic** — core capability
2. **API endpoints** — control + monitoring
3. **UI / UX** — dashboard configuration, status display, management
4. **Documentation** — user guides and operational docs
5. **Scalability** — architected for future expansion

**Example — Network Discovery Node** is complete when: agent-side scanning (ICMP/ARP/SNMP), server-side data + API, dashboard for designating the discovery node + viewing discovered devices + configuring scan schedules + IP ranges/exclusions, status indicators, future-proof data model supporting multiple discovery methods.

**Features shipped without their UI / configuration interfaces are incomplete and will be rejected.** Same standard for backend-only implementations, features requiring API expertise to configure, and designs that paint into architectural corners.

### Living roadmap (MANDATORY)

`projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` is the single living record. `[ ]` = planned, `[x]` = shipped (annotate with date).

- **Before building:** read the feature's roadmap entry for intent/scope. New work that isn't on the roadmap gets an entry first.
- **When shipping or modifying a feature:** update its roadmap entry in the SAME change — flip `[ ]` → `[x]` with a date, or revise/add the item. **Code change without the matching roadmap update is incomplete** (same standard as shipping without UI).
- **Don't over-claim:** if only part is done, keep `[ ]` and annotate the partial scope (e.g. "TCP probing shipped; ICMP/ARP/SNMP pending") rather than flipping.
- `/rmm-audit`'s roadmap pass is the **backstop** that reconciles drift — not the primary maintainer. Dev work keeps the roadmap honest; the audit catches what slipped.

### AI-optional operation

GuruRMM must be fully functional **without** requiring AI agents to operate. All functionality accessible via the traditional dashboard / API; configuration via standard interfaces; usable by MSP techs with zero AI/ML knowledge; deterministic, reliable operation for production.

AI features (agentic analysis, agentic command routing) are **enhancements** — users choose whether to enable them. Production stability over experimental features.

### Planning questions for every feature

- How does an admin configure this in the dashboard?
- What does the status display look like?
- How do we expand this in v2/v3?
- Does this work if AI services are unavailable?

---

## Webhook docs-only build guard (SPEC-020 Phase 0)

The GuruRMM build webhook (`gururmm-webhook.service` → `/opt/gururmm/webhook-handler.py` on 172.16.3.30) has a **docs-only build guard** as of 2026-05-30: a push whose every changed file matches `docs/`, `*.md`, `.claude/`, `session-logs/`, `LICENSE`, or `.gitignore` returns `Docs-only change -- build skipped` and triggers no build. **Fail-safe toward building** — no file list or any buildable file → build runs.

Detection uses the Gitea push payload's per-commit `added`/`removed`/`modified` lists (`is_docs_only` / `NON_BUILDABLE`). Verified live (docs push skipped, no build locks, `last-built-commit` unchanged). Backup: `/opt/gururmm/webhook-handler.py.bak-20260530-guard`.

This is **Phase 0** (interim). The full fix migrates RMM CI to Gitea Actions with native `paths-ignore`, matching GuruConnect (ADR-002) — see [[reference_gitea_internal]].

**Caveat about `webhook-handler.py` specifically:** the repo copy `scripts/webhook-handler.py` is STALE (109 lines vs the deployed 206 — predates the split-build refactor) and does NOT contain the guard. Do NOT redeploy it over the host copy; the host is the source of truth until SPEC-020 lands. (The other 6 build scripts auto-sync from `deploy/build-pipeline/` per [[reference_gururmm]] §pipeline-vendoring — this caveat is `webhook-handler.py`-only.)

---

## Pending setup — Mikes-MacBook-Air `install-hooks.sh`

**STATUS:** Genuinely still pending as of 2026-05-27. Verified: gururmm submodule is initialized on the Mac but only default `.sample` hooks are present.

**Action (do this before any gururmm dev on the Mac):**
```bash
cd /Users/azcomputerguru/ClaudeTools/projects/msp-tools/guru-rmm
git pull
bash scripts/install-hooks.sh
```

**What it does:** sets `core.hooksPath = scripts/hooks/` (activates the pre-commit CRLF check), `core.autocrlf=false`, `core.eol=lf` (locally and globally) — prevents sqlx migration checksum drift (root cause: CRLF vs LF sha384 mismatch from Windows commits).

**Why:** the gururmm build server once refused to start after a rebuild because migration file hashes differed between what was stored in `_sqlx_migrations` and the current files. Fixed with `.gitattributes` + per-machine git config. This step applies the git config side. macOS defaults to LF — low-risk; mainly activates the pre-commit guard.

**When complete:** delete this section from this memory file (or remove the file entirely if no other RMM project state has been added).
