From c70cd70070b72dba2b320fe6decda397a9177756 Mon Sep 17 00:00:00 2001
From: Mike Swanson <mike@azcomputerguru.com>
Date: Fri, 29 May 2026 17:24:53 -0700
Subject: [PATCH] feat(skills): add gc-audit skill for GuruConnect end-to-end
 audit

Modeled on rmm-audit but adapted to GuruConnect's architecture: 7 passes
(6 parallel + sequential CI/CD), protobuf 4-way wire-drift matrix, sqlx
compile-time macros allowed (GC norm), Gitea Actions pipeline + deploy host
checks, reconciles docs/FEATURE_ROADMAP.md + TECHNICAL_DEBT.md. Invoke via
/gc-audit; --pass=<name> for a single pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/skills/gc-audit/SKILL.md | 627 +++++++++++++++++++++++++++++++
 1 file changed, 627 insertions(+)
 create mode 100644 .claude/skills/gc-audit/SKILL.md

diff --git a/.claude/skills/gc-audit/SKILL.md b/.claude/skills/gc-audit/SKILL.md
new file mode 100644
index 0000000..0ae7b3d
--- /dev/null
+++ b/.claude/skills/gc-audit/SKILL.md
@@ -0,0 +1,627 @@
+---
+name: gc-audit
+description: |
+  Periodic end-to-end verification of the GuruConnect codebase and CI/CD
+  infrastructure. Runs 6 parallel audit passes: (1) API/route & surface
+  inventory, (2) Rust code quality & standards, (3) TypeScript/dashboard
+  quality, (4) protocol & wire-format integrity (proto <-> prost <-> manual TS
+  decode), (5) security & remote-session integrity, (6) docs/roadmap
+  reconciliation. A 7th sequential pass audits CI/CD pipeline health (Gitea
+  Actions workflows, runner registration, clippy/audit gates, deploy host).
+  Produces a timestamped audit report and updates the living docs
+  (FEATURE_ROADMAP.md, TECHNICAL_DEBT.md). Takes 10-20 minutes.
+
+  Invoke explicitly only — no auto-trigger. Use /gc-audit for a full audit.
+  Optional arg: --pass=<name> to run a single pass
+  (api, rust, ts, protocol, security, docs, pipeline).
+  The docs pass reconciles FEATURE_ROADMAP.md / TECHNICAL_DEBT.md against the
+  code and cleans up stale entries.
+---
+
+# GuruConnect End-to-End Audit
+
+Periodic full-stack sanity check for **GuruConnect** — the standalone MSP remote-desktop
+product (Rust/Axum relay server + Windows Rust agent + React/TS viewer component library,
+Protobuf-over-WebSocket transport). Read-only by default — findings are written to a report
+file and living docs are updated. No production code is changed.
+
+> **This is GuruConnect, not GuruRMM.** GC diverges from the RMM audit in ways that matter —
+> do NOT copy RMM assumptions. The biggest traps, called out where they apply below:
+> - **sqlx compile-time macros (`sqlx::query!` / `query_as!`) are the GC NORM and are allowed.**
+>   RMM bans them; GC does not. Do not flag them as violations.
+> - **Wire format is Protobuf**, not RMM's JSON `AgentMessage`/`ServerMessage` enums. The
+>   integrity pass chases drift across four artifacts: `proto/guruconnect.proto` →
+>   prost-generated agent code → prost-generated server code → **hand-written binary decode in
+>   `dashboard/src/lib/protobuf.ts` (hardcoded message IDs)**. That manual TS decoder is GC's
+>   signature failure mode.
+> - **The dashboard is a React component library + server-served static HTML**
+>   (`server/static/{login,dashboard,viewer}.html`), NOT a React Router SPA. There is no
+>   `App.tsx` route tree and no `dashboard/src/api/client.ts`. The surface pass adapts.
+> - **CI is Gitea Actions** (`.gitea/workflows/*.yml`) with a Windows runner on Pluto — not
+>   RMM's `webhook-handler.py` + `build-shared.sh` pipeline.
+
+---
+
+## Execution Overview
+
+```
+Phase 0: Context load (coordinator reads key files)
+Phase 1: Spawn 6 parallel audit agents (codebase passes A-F)
+Phase 2: Run CI/CD pipeline audit (Agent G — sequential; SSH to deploy host)
+Phase 3: Collect findings, aggregate, score
+Phase 4: Write report + update living docs
+Phase 5: Present summary to user
+```
+
+The audit is orchestrated here (Claude coordinator). All codebase passes run in parallel
+subagents. The pipeline pass runs sequentially after (it touches live state via SSH / HTTP).
+Each agent returns structured findings; the coordinator aggregates and writes the final report.
+
+### Model (MANDATORY)
+
+**Always run every audit pass on Opus.** Spawn each agent with `model: "opus"` (the `opus`
+alias resolves to the latest Opus). This overrides default complexity-based routing — do NOT
+downgrade any pass to Sonnet or Haiku, even the lower-stakes ones (API surface, TypeScript).
+The coordinator orchestration also runs on Opus.
+
+### Repo root
+
+All paths below are relative to `projects/msp-tools/guru-connect/` unless prefixed otherwise.
+GuruConnect is a **separate Gitea repo** (`azcomputerguru/guru-connect`), not a submodule of
+the monorepo in the RMM sense — it lives at `projects/msp-tools/guru-connect/` with its own
+`.git`. Deploy host: **172.16.3.30:3002**, systemd service `guruconnect.service`.
+
+---
+
+## Phase 0: Context Load (Coordinator Reads These)
+
+Before spawning agents, read these yourself:
+
+1. `CLAUDE.md` — GC project instructions, coding standards, ports, auth model
+2. `docs/FEATURE_ROADMAP.md` — planned features (`[ ]`/`[~]`/`[x]` + P1-P3)
+3. `TECHNICAL_DEBT.md` — living debt backlog + "Completed Items" section (repo root, NOT docs/)
+4. `docs/ARCHITECTURE_DECISIONS.md` — ADR-001 (RMM↔GC contract), ADR-002 (release eng)
+5. `docs/specs/SPEC-001-operational-tooling-parity.md` — release-engineering deliverables
+6. `.claude/CODING_GUIDELINES.md` (repo root) — shared standards GC inherits
+
+Capture from `server/src/api/mod.rs` (+ `server/src/main.rs` route registration) the complete
+route list — every `.route(...)` plus the two WebSocket upgrade endpoints in
+`server/src/relay/mod.rs` (`agent_ws_handler`, `viewer_ws_handler`). This becomes the
+**authority route list** passed to Agents A and E.
+
+Also extract every checkbox line from `FEATURE_ROADMAP.md` (with section + priority) into a
+**roadmap claims list** — passed to Agent F for reconciliation against the code.
+
+---
+
+## Phase 1: Parallel Audit Agents
+
+Spawn all six parallel agents (A, B, C, D, E, F) simultaneously in a single message. Each
+agent receives the full context it needs inline — do not assume they share context. (Agent G —
+Pipeline — runs sequentially afterward; it SSHes the live deploy host and hits HTTP endpoints.)
+
+---
+
+### Agent A — API Surface & Route Inventory
+
+**Goal:** Find server endpoints with no UI/consumer exposure, handlers that are dead code, and
+references in the dashboard/static HTML to routes that don't exist.
+
+**Instructions for agent:**
+
+1. Read `server/src/api/mod.rs` and `server/src/main.rs` — extract every `.route(path, method)`
+   into a list grouped by resource (auth, users, sessions, downloads, releases, changelog,
+   health, metrics). Include the two WS endpoints from `server/src/relay/mod.rs`.
+
+2. **The dashboard is NOT a routed SPA.** Instead cross-reference route usage against:
+   - `server/static/login.html`, `dashboard.html`, `viewer.html` — grep for `fetch(`, `/api/`,
+     and `ws`/`wss` URLs the static pages call.
+   - `dashboard/src/hooks/useRemoteSession.ts` — the WS connection URLs it opens.
+   - `dashboard/src/components/*.tsx` — any REST calls.
+
+3. Classify:
+   - Server route never referenced by any static page / component / hook → **ORPHANED ROUTE**
+     (dead code vs. intentionally external/integration — distinguish by context, e.g. routes the
+     RMM integration calls per ADR-001 are not dead).
+   - A `fetch`/WS URL in the frontend that matches no server route → **BROKEN CALL**.
+   - Method mismatch (frontend POSTs to a GET route) → **METHOD MISMATCH**.
+
+4. For each API resource group, assess whether the UI (static pages + viewer component) exposes
+   the major operations. Flag resources with full server CRUD but no UI surface.
+
+5. Return structured findings: `[SEVERITY] Description — file:line`.
+
+---
+
+### Agent B — Rust Code Quality & Standards
+
+**Goal:** Find violations of GC's Rust standards and common quality issues across server + agent.
+
+**Instructions for agent:**
+
+Read `CLAUDE.md` (GC standards section) and `.claude/CODING_GUIDELINES.md` first. GC standards:
+`tracing` for logging (not `println!`/`log`), `anyhow` in binaries, `thiserror` in libraries,
+`async`/`await` preferred, clippy clean.
+
+**Compliance checks:**
+- `.unwrap()` / `.expect()` outside `#[cfg(test)]` — panic in production. Flag each with context.
+  `.expect("invariant reason")` on a truly-impossible path is acceptable if the reason is clear.
+- `todo!()` / `unimplemented!()` in non-test production paths.
+- `println!` / `eprintln!` used for logging instead of `tracing::` macros.
+- `format!()` used to build SQL strings (injection risk — parameterize instead).
+- **DO NOT flag `sqlx::query!` / `sqlx::query_as!` compile-time macros.** They are the GC
+  convention (the codebase relies on compile-time query checking). This is the inverse of the
+  RMM rule — flagging them here is a false positive.
+
+**Auth coverage (server):**
+- Read `server/src/api/mod.rs` + `server/src/auth/mod.rs`. Identify which route groups go through
+  the `AuthenticatedUser` extractor / auth middleware vs. which are public (login, health,
+  downloads, metrics may be intentionally public).
+- Verify the **agent plane and viewer/admin plane are separated**: the agent WS
+  (`agent_ws_handler`, auth via `support_code` OR `api_key`) and the viewer WS
+  (`viewer_ws_handler`, auth via JWT) must not accept each other's credentials. Any non-public
+  admin route reachable without JWT → `[CRITICAL]`.
+- Confirm JWT secret + min-length enforcement at startup (`server/src/main.rs`) and the logout
+  token blacklist (`server/src/auth/token_blacklist.rs`) is actually consulted on each request.
+
+**Logging hygiene:**
+- Grep `tracing::` calls that include JWT secrets, API keys, support codes, passwords, or PII
+  (emails, usernames). These must be redacted.
+
+**Error handling:**
+- HTTP handlers returning 500 with raw `e.to_string()` — leaks internals to callers. Log
+  server-side, return a generic message.
+
+**Search paths:** `server/src/` and `agent/src/`. Exclude generated proto (`OUT_DIR`) and
+`server/src/db/mod.rs` re-exports.
+
+Return structured findings with file:line references.
+
+---
+
+### Agent C — TypeScript / Dashboard Quality
+
+**Goal:** Find dashboard quality issues, with special focus on the hand-written protobuf decoder
+(GC has no schema library on the TS side — correctness is manual).
+
+**Instructions for agent:**
+
+The dashboard (`dashboard/`) is a **React component library** (peer-dep React, no app router,
+no bundler in-repo). Main artifacts: `components/RemoteViewer.tsx`, `components/SessionControls.tsx`,
+`hooks/useRemoteSession.ts`, `lib/protobuf.ts`, `types/protocol.ts`.
+
+**TypeScript quality:**
+- `any` annotations in `dashboard/src/` — each is a type-safety gap (the binary/canvas code is
+  exactly where `any` hides bugs).
+- `@ts-ignore` / `@ts-expect-error` — note reason and whether still needed.
+- `console.log` / `console.error` left in non-dev paths.
+- Hardcoded server URLs instead of a passed `serverUrl` prop / config.
+
+**Manual protobuf decoder correctness (`lib/protobuf.ts`) — HIGH PRIORITY:**
+- The decoder parses binary frames with `DataView` and **hardcoded message IDs** (e.g.
+  `MSG_VIDEO_FRAME`, `MSG_MOUSE_EVENT`, `MSG_KEY_EVENT`). Verify these IDs and field offsets
+  match `proto/guruconnect.proto` field numbers / wire layout. A mismatch silently corrupts
+  frames or events. (Agent D cross-checks the same surface from the proto side — coordinate via
+  the report; this side checks the TS implementation correctness.)
+- Bounds checking: does the decoder validate buffer length before reading offsets? A short/hostile
+  frame should not throw an unhandled error or read OOB.
+
+**Component patterns:**
+- `RemoteViewer.tsx` canvas rendering: BGRA→RGBA conversion correctness; is the canvas sized to
+  the frame? Are out-of-order frames (the `sequence` field) handled or dropped?
+- `useRemoteSession.ts`: WebSocket lifecycle — reconnect handling, cleanup on unmount, error
+  surfacing (a dropped session should not silently hang).
+- Icon-only buttons without `aria-label`/`title`; inputs without `<label>`.
+
+**Search paths:** `dashboard/src/` only.
+
+Return structured findings with file:line references.
+
+---
+
+### Agent D — Protocol & Wire-Format Integrity
+
+**Goal:** This is GC's signature pass. Detect drift across the four representations of the wire
+protocol, plus migration/version integrity.
+
+**Instructions for agent:**
+
+**Four-way protocol drift (the core check):**
+1. Read `proto/guruconnect.proto` — list every top-level `Message` `oneof` variant and each
+   message's fields with their **field numbers**. Note `session_type`, `VideoFrame`/`RawFrame`/
+   `EncodedFrame`, `MouseEvent`, `KeyEvent`, `AgentStatus`, `AdminCommand`, `UpdateInfo`,
+   `Heartbeat`/`HeartbeatAck`, `StartStream`/`StopStream`.
+2. Agent side: `agent/src/transport/mod.rs` + `agent/src/transport/websocket.rs` — confirm it
+   encodes/decodes via prost (`encode_to_vec` / `Message::decode`) and handles every inbound
+   variant it should. Any server→agent variant with no handler → dead/missing.
+3. Server side: `server/src/relay/mod.rs` — confirm the relay decodes agent frames and forwards
+   the right variants to viewers, and decodes viewer input and forwards to the agent. Any proto
+   variant the relay never matches → dead code or missing relay path.
+4. Dashboard side: `dashboard/src/lib/protobuf.ts` hardcoded message IDs + `types/protocol.ts`
+   field names. **Cross-check the hardcoded IDs against the proto field numbers** and the TS field
+   names against the proto field names. Mismatch → `[HIGH]` (silent frame/event corruption).
+
+   Build the drift matrix: `message/field | proto | agent (prost) | server (prost) | dashboard (manual)`
+   and flag every row that isn't consistent across all four.
+
+**Migration integrity:**
+- List `server/migrations/*.sql` — verify sequential numbering with no gaps (currently
+  `001_initial_schema`, `002_user_management`, `003_auto_update`).
+- For each `CREATE TABLE` (users, machines, sessions, support_codes, events, releases…), verify a
+  corresponding `server/src/db/<name>.rs` module exists and its struct fields match the columns.
+
+**Version consistency:**
+- `agent/Cargo.toml`, `server/Cargo.toml`, `dashboard/package.json` versions — are they in sync?
+  (All were `0.2.0` at last map.) The agent embeds version via `agent/build.rs` (CARGO_PKG_VERSION
+  + git hash). Note divergence; there is **no automatic version bump yet** (SPEC-001 §3 pending) —
+  so out-of-sync versions are a `[MEDIUM]` worth surfacing, not necessarily a bug.
+
+**WebSocket frame validation:**
+- In `server/src/relay/mod.rs`, are inbound frames size-capped before decode/relay? An unbounded
+  `VideoFrame` from a hostile agent → server OOM. No cap → `[HIGH]` (see Agent E for the security
+  framing).
+
+Return structured findings with file:line references and the drift matrix.
+
+---
+
+### Agent E — Security & Remote-Session Integrity
+
+**Goal:** GC is a remote-control product — the threat surface is session hijack, input injection,
+and relay abuse. Verify the boundaries the SEC* audits established still hold and check the gaps
+they flagged.
+
+**Instructions for agent:**
+
+Read the existing security audit docs first so you don't re-report settled items (note their
+status and only re-flag if the code regressed): `SEC3_SQL_INJECTION_AUDIT.md`,
+`SEC4_AGENT_VALIDATION_AUDIT.md` / `_COMPLETE.md`, `SEC5_SESSION_TAKEOVER_AUDIT.md` / `_COMPLETE.md`,
+and `TECHNICAL_DEBT.md` security items.
+
+**Session & auth boundaries:**
+- Viewer WS auth: `viewer_ws_handler` validates a JWT (query param). Confirm the token is verified
+  (signature + expiry + blacklist), not just parsed. A viewer joining a session must be authorized
+  for *that* session, not any session.
+- Agent WS auth: `agent_ws_handler` accepts `support_code` OR `api_key`. Confirm support codes are
+  single-use and **revocation updates the in-memory store immediately** (a revoked code must fail
+  even if the agent reconnects before a server restart — `server/src/db/support_codes.rs` /
+  in-memory map).
+- Session takeover: sessions keyed by UUID, heartbeat timeout ~90s. Confirm a new viewer cannot
+  attach to or hijack an existing session without authorization, and that session IDs aren't
+  guessable/loggable in a way that enables replay.
+
+**Relay abuse / DoS:**
+- Frame size caps on inbound WS messages (agent video frames AND viewer input) — unbounded →
+  `[HIGH]` OOM/DoS vector.
+- Input event injection: viewer→agent mouse/key events — is there rate limiting or a bounded queue
+  on the agent input path (`agent/src/input/`)? Unbounded input spam → agent CPU/queue exhaustion.
+- Rate limiting on auth endpoints (`server/src/middleware/rate_limit.rs`, `tower_governor`) — still
+  applied to `/api/auth/login`? Confirm it's wired, not just present.
+
+**Secrets & transport:**
+- JWT secret, agent API key sourced from env (not hardcoded) and length-checked at startup.
+- TLS/WSS required for relay; no plaintext fallback that carries frames or credentials.
+- Passwords hashed with Argon2id (`server/src/auth/password.rs`).
+
+Return structured findings with file:line references. Severity by impact (a session-hijack path is
+`[CRITICAL]` even if the fix is small).
+
+---
+
+### Agent F — Docs & Roadmap Reconciliation
+
+**Goal:** Make GC's living docs tell the truth. Reconcile every roadmap checkbox and debt item
+against the actual code.
+
+**Runs in parallel with A-E (read-only code search, no SSH).**
+
+**Instructions for agent:**
+
+1. Read `docs/FEATURE_ROADMAP.md` and extract every checkbox line with state (`[ ]`/`[~]`/`[x]`),
+   section, and priority. Also read `TECHNICAL_DEBT.md` (repo root; items + the "Completed Items"
+   section) and `docs/specs/SPEC-001-operational-tooling-parity.md` (its §1-§6 deliverables).
+
+2. For EACH item, find the implementing artifact in code — do NOT trust the checkbox:
+   - API/endpoint features → `server/src/api/mod.rs` routes + handler module
+   - Relay/session features → `server/src/relay/mod.rs`, `server/src/session/`
+   - Protocol features → `proto/guruconnect.proto` + agent/server prost usage
+   - Agent capabilities (capture, input, tray, update) → `agent/src/`
+   - Dashboard/viewer features → `dashboard/src/components|hooks/*` + static HTML
+   - CI/release deliverables (SPEC-001: versioning, signing, changelog API, gc-feature-request
+     skill, coord-API) → `.gitea/workflows/*`, `scripts/*`, `.claude/commands/gc-feature-request.md`
+   Use Grep/GrepAI. Cite the exact artifact (file:line, migration name, route path, workflow job).
+
+3. Classify each item:
+   - **STALE-INCOMPLETE** — `[ ]`/`[~]` but code fully implements it end-to-end → recommend `[x]`.
+   - **PARTIAL** — `[ ]`/`[~]`, some layers exist but not end-to-end for the stated scope → keep
+     `[ ]`/`[~]`, recommend an inline scope annotation. Do NOT flip to `[x]`.
+   - **STALE-COMPLETE** — `[x]` but code does not implement it (never built / reverted) →
+     recommend flip to `[ ]`, flag `[HIGH]` (the roadmap is lying).
+   - **ACCURATE** — matches. No change.
+
+4. For `TECHNICAL_DEBT.md`: identify debt items the code shows are now fixed → recommend moving them
+   to the "Completed Items" section with a date. Identify items still open that the code confirms.
+
+5. Be conservative: only flip `[ ]`→`[x]` when evidence is unambiguous AND end-to-end. When in
+   doubt → PARTIAL with a note. Bias toward under-flipping.
+
+Return two tables:
+`roadmap item | section | current | verdict | proving-or-missing artifact`
+`debt item | current status | verdict (fixed/open/partial) | artifact`
+
+---
+
+### Agent G — CI/CD Pipeline & Deploy Health
+
+**Goal:** Verify the build/deploy infrastructure is functioning and the SPEC-001 quality gates are
+in the state the docs claim. Catches issues invisible to codebase-only audits: broken workflows,
+unregistered runners, stale deploys, gate drift.
+
+**NOTE:** Runs sequentially (after A-F) because it SSHes the live deploy host and hits HTTP
+endpoints. Read-only — checks state, never triggers a build or deploy.
+
+**Instructions for agent:**
+
+**1. Gitea Actions workflow integrity (read the repo files):**
+- `.gitea/workflows/build-and-test.yml` — confirm jobs: `build-server` (fmt --check, clippy,
+  build, test), `build-agent` (Windows MSVC on the Pluto runner, PROTOC + crt-static), and
+  `security-audit` (`cargo audit`). Note whether clippy/audit are **informational** (warn-only) or
+  **hard-fail** (`-D warnings` / fail-on-vuln).
+- `.gitea/workflows/deploy.yml` — confirm trigger (tag `v*.*.*` / manual) and whether the actual
+  SSH deploy step is real or still a stub (`echo "[INFO] SSH to 172.16.3.30…"`).
+- `.gitea/workflows/release.yml` (if present) — SPEC-001 §2-§4: version bump, changelog gen,
+  `jsign` + Azure Trusted Signing step. Note which deliverables are wired vs. pending.
+- `bash -n` is not applicable to YAML; instead sanity-check each workflow for: valid `on:` triggers,
+  every `uses:`/`run:` step present, no job referencing a secret that the audit notes as unset.
+
+**SPEC-001 gate cross-check (ties to the active lint-debt work):** the SPEC-001 quality gates aim to
+flip clippy to hard-fail + enforce `cargo audit`. Report the CURRENT enforced state vs. the SPEC-001
+target so it's clear whether the tightening has landed. (~65 pre-spec clippy warnings were noted as
+informational at last map — confirm count/state.)
+
+**2. Gitea runner registration & health:**
+- TECHNICAL_DEBT.md item #1 flagged runner registration as CRITICAL/blocking. Verify a runner is
+  registered and online for both `ubuntu-latest` (server/audit jobs) and the Windows/Pluto runner
+  (agent job). On the Gitea host or via the Gitea API, check the actions runner list. If no Windows
+  runner is online → `[CRITICAL]` agent builds cannot run. Reference `.claude/machines/pluto.md` for
+  the Pluto runner setup (PROTOC at `C:\protoc\bin\protoc.exe`, Administrator `.cargo`/`.rustup`).
+
+**3. Deploy host health (`ssh guru@172.16.3.30`):**
+```bash
+systemctl status guruconnect.service --no-pager
+curl -s -o /dev/null -w '%{http_code}' http://localhost:3002/health
+curl -s http://localhost:3002/metrics | head -20
+ls -lht /home/guru/guru-connect/server/migrations/
+```
+- `guruconnect.service` not `active (running)` → `[CRITICAL]`.
+- `/health` non-200 / refused → `[CRITICAL]`.
+- `/metrics` empty or refused → `[HIGH]` (Prometheus scrape broken).
+- Confirm the binary on disk matches a recent commit:
+  `cd /home/guru/guru-connect && git log --oneline -5` and compare to the running version
+  (the service version vs. `git rev-parse HEAD`). Months-old running binary while git shows recent
+  work → `[HIGH]` deploy stuck (consistent with the stubbed deploy step).
+- Confirm migrations applied: query `_sqlx_migrations` (003 should be present). Missing → `[HIGH]`.
+
+**4. Artifact distribution:**
+- Agent download served at `https://connect.azcomputerguru.com/downloads/guruconnect.exe`
+  (or the path configured in `server/src/api/downloads.rs`). Verify the file exists and its mtime is
+  recent relative to agent commits. Stale/missing → `[HIGH]` (clients download an old agent).
+- Confirm the served EXE is **signed** if SPEC-001 §2 signing has landed; unsigned while signing is
+  marked done → `[HIGH]`.
+
+**5. Monitoring stack (per INFRASTRUCTURE_STATUS.md):**
+- Prometheus scraping GC `/metrics`; Grafana dashboard reachable. Backup timer
+  (`guruconnect-backup.timer`) enabled: `systemctl status guruconnect-backup.timer --no-pager`.
+  Disabled/failed backup timer → `[MEDIUM]`.
+
+Return structured findings with source (file path + line, or command + output) for every finding.
+
+---
+
+## Phase 3: Aggregating Findings
+
+Collect all agents' outputs. Classify each finding:
+
+| Severity | Meaning |
+|----------|---------|
+| `[CRITICAL]` | Security vuln (session hijack, auth bypass), data loss, production crash, or broken-build/deploy blocker |
+| `[HIGH]` | Functional gap blocking a core workflow, protocol drift causing silent corruption, or standards violation with user impact |
+| `[MEDIUM]` | Code quality issue, version skew, or inconsistency without immediate impact |
+| `[LOW]` | Minor polish, dead code, missing comment |
+| `[INFO]` | Neutral observation, completed item, or context note |
+
+Deduplicate: if two agents flag the same issue from different angles (e.g. Agent C on the TS
+decoder and Agent D on the proto side of the same field), merge into one finding with both
+references.
+
+---
+
+## Phase 4: Write Report + Update Living Docs
+
+### Report Location
+
+Write to: `projects/msp-tools/guru-connect/reports/YYYY-MM-DD-gc-audit.md` (use the actual date).
+**The `reports/` directory does not exist yet — create it on first run.** If a report from today
+already exists, append a `-2` suffix.
+
+### Report Format
+
+```markdown
+# GuruConnect Audit Report — YYYY-MM-DD
+
+**Auditor:** Claude (<model id>)
+**Passes:** API Surface, Rust Quality, TypeScript/Dashboard, Protocol Integrity, Security & Session, Docs Reconciliation, CI/CD Pipeline
+**Previous audit:** [link to prior report if one exists, else "First audit"]
+
+---
+
+## Executive Summary
+
+| Pass | Total | Critical | High | Medium | Low |
+|------|-------|---------|------|--------|-----|
+| API Surface | N | N | N | N | N |
+| Rust Quality | N | N | N | N | N |
+| TypeScript/Dashboard | N | N | N | N | N |
+| Protocol Integrity | N | N | N | N | N |
+| Security & Session | N | N | N | N | N |
+| CI/CD Pipeline | N | N | N | N | N |
+| **TOTAL** | **N** | **N** | **N** | **N** | **N** |
+
+**Requires immediate action:** [one line per CRITICAL finding]
+
+---
+
+## Pass 1: API Surface
+### [SEVERITY] Finding Title
+**File:** path:LINE
+**Detail:** What the problem is, why it matters.
+**Recommendation:** What to do.
+[repeat per finding]
+
+---
+## Pass 2: Rust Code Quality
+## Pass 3: TypeScript / Dashboard Quality
+## Pass 4: Protocol & Wire-Format Integrity
+[include the 4-way drift matrix]
+## Pass 5: Security & Remote-Session Integrity
+## Pass 6: CI/CD Pipeline Health
+[Gitea Actions workflow state, runner registration, gate state vs SPEC-001 target, deploy host, artifact freshness]
+
+---
+
+## FEATURE_ROADMAP.md Delta (Agent F)
+Checkboxes corrected to match code reality this audit:
+- `[ ]`/`[~]` → `[x]` **<item>** — shipped. Proof: `<artifact>`.
+- `[x]` → `[ ]` **<item>** — marked complete but NOT in code (regression / never built). `[HIGH]`
+Annotated as partial (scope clarified): - `[ ]` **<item>** (<scope note>) — `<artifact>`
+Verified accurate (no change): N items.
+
+## TECHNICAL_DEBT.md Delta (Agent F)
+Items moved to "Completed Items": - **<item>** — fixed. Proof: `<artifact>`.
+Still open (confirmed): N items.
+
+---
+
+## Recommended Action Order
+1. [CRITICAL items, sorted by impact]
+2. [HIGH items]
+3. [MEDIUM items — can be batched]
+```
+
+### Update Living Docs
+
+After writing the report, apply Agent F's reconciliation (this is the cleanup the audit owns;
+editing living docs fits the "living docs are updated" exception to read-only):
+
+- **`docs/FEATURE_ROADMAP.md`** — default is reconcile-and-flip:
+  - STALE-INCOMPLETE → flip `[ ]`/`[~]` to `[x]` for every item proven shipped end-to-end; optionally
+    append `(verified <date>)`.
+  - PARTIAL → leave the box, append the scope annotation. Never flip a partial to `[x]`.
+  - STALE-COMPLETE → flip `[x]` to `[ ]`, add `[REGRESSION — flagged YYYY-MM-DD]`, mirror as a
+    `[HIGH]` finding in the report.
+- **`TECHNICAL_DEBT.md`** — move confirmed-fixed items into the "Completed Items" section with a date;
+  leave open items in place.
+- Every doc change MUST also appear in the report's Delta section with its proving artifact — no
+  silent edits. When evidence is ambiguous, do NOT change the doc; record as PARTIAL/INFO for human
+  review. Bias toward under-flipping.
+
+---
+
+## Phase 5: User Summary
+
+Present a concise summary to the user:
+
+```
+Audit complete. Report: projects/msp-tools/guru-connect/reports/YYYY-MM-DD-gc-audit.md
+
+CRITICAL (N): [one-line each]
+HIGH (N):     [one-line each]
+MEDIUM (N):   Batched in report.
+
+Protocol drift: [one-line — e.g. "proto/agent/server/dashboard consistent" or the worst mismatch]
+Pipeline: [one-line — e.g. "all green" or highest-severity finding; note clippy/audit gate state vs SPEC-001]
+Roadmap: N checkboxes corrected (N stale-incomplete flipped, N partial annotated, N regressions flagged).
+Tech debt: N items moved to Completed.
+
+Recommended first action: [the single highest-priority finding]
+```
+
+Then ask: "Want me to start on any of these findings?"
+
+---
+
+## Conventions
+
+- **Read, don't run.** Never executes production code or triggers builds/deploys. Reads files,
+  uses Grep/GrepAI, and (Agent G only) runs read-only status/HTTP checks.
+- **Derive from code, not docs.** Treat all `.md`/`.json` status docs as potentially stale. Code is
+  truth. (The whole point of Agent F.)
+- **Be specific.** Every finding needs a file:line reference. Vague findings are useless.
+- **No false positives.** If something looks wrong but context makes it acceptable, note it `[INFO]`
+  with the reason. (Especially: `sqlx::query!` macros are fine here; informational clippy/audit gates
+  are a known SPEC-001 state, not a bug — report the state, don't cry wolf.)
+- **Severity is impact, not effort.** A two-line fix can be `[CRITICAL]` if it's a session-hijack path.
+- **Commit the report.** After writing, delegate to the Gitea Agent to commit the report file and the
+  living-doc updates to the `guru-connect` repo (not any code fixes — those are separate work items).
+  Respect any active coord lock on `guruconnect` before editing `.gitea/workflows` or docs.
+
+---
+
+## Reference: Key Files by Area
+
+### Server (`server/src/`)
+| Area | Key Files |
+|------|-----------|
+| Routes | `api/mod.rs` (+ `main.rs` registration), submodules `api/{auth,users,downloads,releases,changelog}.rs` |
+| WebSocket relay | `relay/mod.rs` (`agent_ws_handler`, `viewer_ws_handler`) |
+| Sessions | `session/mod.rs` |
+| DB layer | `db/mod.rs`, `db/{users,machines,sessions,events,support_codes,releases}.rs` |
+| Migrations | `migrations/00{1,2,3}_*.sql` |
+| Auth | `auth/{jwt,token_blacklist,password,mod}.rs` |
+| Rate limiting | `middleware/rate_limit.rs` |
+| Generated proto | `OUT_DIR` via `server/build.rs` (do not audit generated code) |
+
+### Agent (`agent/src/`)
+| Area | Key Files |
+|------|-----------|
+| Transport / wire | `transport/mod.rs`, `transport/websocket.rs` |
+| Capture | screen/DXGI-GDI capture modules |
+| Input injection | `input/` |
+| Version embed | `agent/build.rs` |
+
+### Dashboard (`dashboard/src/`)
+| Area | Key Files |
+|------|-----------|
+| Viewer component | `components/RemoteViewer.tsx`, `components/SessionControls.tsx` |
+| Session hook | `hooks/useRemoteSession.ts` |
+| Manual protobuf | `lib/protobuf.ts` (hardcoded message IDs — drift hazard) |
+| Protocol types | `types/protocol.ts` |
+| Served static UI | `server/static/{login,dashboard,viewer}.html` |
+
+### Protocol
+| Area | Path |
+|------|------|
+| Proto definition | `proto/guruconnect.proto` |
+
+### CI/CD & Infra
+| Area | Path |
+|------|------|
+| CI gate | `.gitea/workflows/build-and-test.yml` |
+| Deploy | `.gitea/workflows/deploy.yml` |
+| Release/signing | `.gitea/workflows/release.yml`, SPEC-001 |
+| Runner setup | `scripts/install-gitea-runner.sh`, `.claude/machines/pluto.md` |
+| Deploy host | 172.16.3.30:3002, systemd `guruconnect.service` |
+| Monitoring | `infrastructure/{prometheus.yml,grafana-dashboard.json,alerts.yml}`, `guruconnect-backup.timer` |
+
+### Docs / Standards
+| Area | Path |
+|------|------|
+| GC instructions/standards | `CLAUDE.md` |
+| Shared coding standards | `.claude/CODING_GUIDELINES.md` (monorepo root) |
+| Feature roadmap | `docs/FEATURE_ROADMAP.md` |
+| Tech debt backlog | `TECHNICAL_DEBT.md` (repo root) |
+| Architecture decisions | `docs/ARCHITECTURE_DECISIONS.md` (ADR-001 RMM↔GC contract, ADR-002 release eng) |
+| Release-eng spec | `docs/specs/SPEC-001-operational-tooling-parity.md` |
+| Changelogs (SPEC-001 changelog API) | `changelogs/LATEST_{SERVER,AGENT,DASHBOARD}.md`, `changelogs/<component>/v*.md`, `CHANGELOG.md` |
+| Security audits | `SEC{3,4,5}_*_AUDIT.md` / `_COMPLETE.md` |
+| Past audit reports | `reports/` (create on first run) |