From e5ccb6a71a29371abc8954a90d7b8f4fa5843a8c Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Fri, 29 May 2026 18:23:46 -0700 Subject: [PATCH] feat(gc-audit): use .claude/standards + reconcile specs/plans - Load .claude/standards/ (index.yml + files) as the compliance baseline; Rust/TS passes now cite the specific standard each finding violates - Glob all docs/specs/SPEC-*.md (incl. SPEC-002) + specs/*/plan.md; Pass F reconciles SPEC phases and plan.md [DONE] markers against code (3rd table) - Extract a planned-work list from SPEC-002 + active plans; tag findings that match already-planned work as [TRACKED] so mid-rebuild audits surface net-new Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/gc-audit/SKILL.md | 56 +++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 9 deletions(-) diff --git a/.claude/skills/gc-audit/SKILL.md b/.claude/skills/gc-audit/SKILL.md index 0ae7b3d..cf8ed07 100644 --- a/.claude/skills/gc-audit/SKILL.md +++ b/.claude/skills/gc-audit/SKILL.md @@ -14,8 +14,9 @@ description: | Invoke explicitly only — no auto-trigger. Use /gc-audit for a full audit. Optional arg: --pass= 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. + The docs pass reconciles FEATURE_ROADMAP.md, TECHNICAL_DEBT.md, the docs/specs/SPEC-*.md, + and the specs/*/plan.md task markers against the code; quality passes check code against + the granular .claude/standards/ files. Cleans up stale entries. --- # GuruConnect End-to-End Audit @@ -81,8 +82,19 @@ Before spawning agents, read these yourself: 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 +5. **All** `docs/specs/SPEC-*.md` (Glob them so new specs are auto-picked-up) — the architecture/feature + specs. SPEC-001 = release-engineering parity; **SPEC-002 = the v2 modernization architecture — read it: + it defines the in-flight rebuild and which v1 weaknesses are *already planned* to be replaced, so passes + can distinguish known/planned from net-new.** +6. `specs/*/` shape-spec folders (`plan.md`/`shape.md`/`references.md`/`standards.md`) — pre-implementation + plans (e.g. `specs/v2-secure-session-core/`, `specs/native-remote-control/`). `plan.md` is the + implementation source-of-truth and tracks progress via `[DONE]` task markers — a reconciliation target + for Agent F. +7. `.claude/CODING_GUIDELINES.md` **+ `.claude/standards/` — read `index.yml`, then the relevant standard + files** (repo root). `.claude/standards/` is the **compliance baseline** the quality passes check code + against (not just the looser CODING_GUIDELINES): `security/credential-handling`, `api/response-format`, + `gururmm/sqlx-migrations`, `gururmm/platform-parity`, `conventions/{naming,no-emojis,output-markers}`, + `git/commit-style`. Pass the relevant standards **and their key rules** to Agents B and C. 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 @@ -92,6 +104,13 @@ route list — every `.route(...)` plus the two WebSocket upgrade endpoints in 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. +**During the v2 rebuild (SPEC-002):** extract a **planned-work list** from SPEC-002 and the active +`specs/*/plan.md` files — the known v1 weaknesses already scheduled for replacement (the relay-auth +CRITICALs, the broken web protobuf codec, the deploy stub, etc.). Pass this list to every pass. A finding +that matches already-planned work is still reported, but tagged **`[TRACKED — SPEC-002 / ]`** instead +of presented as net-new, so an audit run mid-rebuild does not drown the report in things already decided. +**Net-new findings (in no spec/plan) are the signal that matters most.** + --- ## Phase 1: Parallel Audit Agents @@ -139,9 +158,15 @@ references in the dashboard/static HTML to routes that don't exist. **Instructions for agent:** -Read `CLAUDE.md` (GC standards section) and `.claude/CODING_GUIDELINES.md` first. GC standards: +Read `CLAUDE.md` (GC standards section), `.claude/CODING_GUIDELINES.md`, **and the relevant +`.claude/standards/` files the coordinator passed you** first. GC standards: `tracing` for logging (not `println!`/`log`), `anyhow` in binaries, `thiserror` in libraries, -`async`/`await` preferred, clippy clean. +`async`/`await` preferred, clippy clean. **Audit against the concrete `.claude/standards/` rules and +cite the standard each finding violates** — `security/credential-handling` (no hardcoded secrets; +hashed/short-lived tokens; log auth attempts), `api/response-format` (consistent error envelope, no raw +`e.to_string()` to clients, kebab-case segments, idempotent migrations), `gururmm/sqlx-migrations` +(`IF NOT EXISTS`, server-applied, no manual pre-apply), `conventions/naming` (Rust/proto/DB casing), +`conventions/no-emojis`, `git/commit-style`. **Compliance checks:** - `.unwrap()` / `.expect()` outside `#[cfg(test)]` — panic in production. Flag each with context. @@ -190,6 +215,10 @@ The dashboard (`dashboard/`) is a **React component library** (peer-dep React, n no bundler in-repo). Main artifacts: `components/RemoteViewer.tsx`, `components/SessionControls.tsx`, `hooks/useRemoteSession.ts`, `lib/protobuf.ts`, `types/protocol.ts`. +**Standards baseline:** audit against the relevant `.claude/standards/` files the coordinator passed +(esp. `conventions/no-emojis`, `conventions/naming`, `conventions/output-markers` for any scripts) and +cite the standard each violation breaks. + **TypeScript quality:** - `any` annotations in `dashboard/src/` — each is a type-safety gap (the binary/canvas code is exactly where `any` hides bugs). @@ -319,7 +348,9 @@ against the actual code. 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). + section), **every** `docs/specs/SPEC-*.md` (Glob them — SPEC-001 §1-§6 deliverables, SPEC-002 v2 + architecture phases + decisions, and any later specs), and **every** `specs/*/plan.md` shape-spec + (its task list + `[DONE]` markers). 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 @@ -329,6 +360,10 @@ against the actual code. - 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` + - **Shape-spec `plan.md` tasks** → find the implementing artifact for each task. A task marked + `[DONE]` but not in code → **STALE-COMPLETE `[HIGH]`** (the plan is lying); implemented but not + marked `[DONE]` → recommend adding the marker. **SPEC-002 phase deliverables** → reconcile each + against code the same way (a phase claimed done that isn't, or shipped-but-unmarked). Use Grep/GrepAI. Cite the exact artifact (file:line, migration name, route path, workflow job). 3. Classify each item: @@ -345,9 +380,10 @@ against the actual code. 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: +Return three tables: `roadmap item | section | current | verdict | proving-or-missing artifact` `debt item | current status | verdict (fixed/open/partial) | artifact` +`spec/plan item (SPEC-NNN phase or specs/ plan.md task) | claimed state | verdict (done / partial / not-started / [DONE]-but-missing) | artifact` --- @@ -621,7 +657,9 @@ Then ask: "Want me to start on any of these findings?" | 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` | +| Architecture/feature specs | `docs/specs/SPEC-*.md` (SPEC-001 release-eng, SPEC-002 v2 architecture, …) | +| Shape-spec plans | `specs/*/{plan,shape,references,standards}.md` (e.g. `v2-secure-session-core`, `native-remote-control`) — `plan.md` `[DONE]` markers are a reconciliation target | +| Granular standards (compliance baseline) | `.claude/standards/index.yml` + `.claude/standards/**/*.md` | | Changelogs (SPEC-001 changelog API) | `changelogs/LATEST_{SERVER,AGENT,DASHBOARD}.md`, `changelogs//v*.md`, `CHANGELOG.md` | | Security audits | `SEC{3,4,5}_*_AUDIT.md` / `_COMPLETE.md` | | Past audit reports | `reports/` (create on first run) |