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) <noreply@anthropic.com>
This commit is contained in:
2026-05-29 18:23:46 -07:00
parent df6a2dd5d8
commit e5ccb6a71a

View File

@@ -14,8 +14,9 @@ description: |
Invoke explicitly only — no auto-trigger. Use /gc-audit for a full audit. Invoke explicitly only — no auto-trigger. Use /gc-audit for a full audit.
Optional arg: --pass=<name> to run a single pass Optional arg: --pass=<name> to run a single pass
(api, rust, ts, protocol, security, docs, pipeline). (api, rust, ts, protocol, security, docs, pipeline).
The docs pass reconciles FEATURE_ROADMAP.md / TECHNICAL_DEBT.md against the The docs pass reconciles FEATURE_ROADMAP.md, TECHNICAL_DEBT.md, the docs/specs/SPEC-*.md,
code and cleans up stale entries. 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 # 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) 2. `docs/FEATURE_ROADMAP.md` — planned features (`[ ]`/`[~]`/`[x]` + P1-P3)
3. `TECHNICAL_DEBT.md` — living debt backlog + "Completed Items" section (repo root, NOT docs/) 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) 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 5. **All** `docs/specs/SPEC-*.md` (Glob them so new specs are auto-picked-up) — the architecture/feature
6. `.claude/CODING_GUIDELINES.md` (repo root) — shared standards GC inherits 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 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 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 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. **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 / <spec>]`** 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 ## Phase 1: Parallel Audit Agents
@@ -139,9 +158,15 @@ references in the dashboard/static HTML to routes that don't exist.
**Instructions for agent:** **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, `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:** **Compliance checks:**
- `.unwrap()` / `.expect()` outside `#[cfg(test)]` — panic in production. Flag each with context. - `.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`, no bundler in-repo). Main artifacts: `components/RemoteViewer.tsx`, `components/SessionControls.tsx`,
`hooks/useRemoteSession.ts`, `lib/protobuf.ts`, `types/protocol.ts`. `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:** **TypeScript quality:**
- `any` annotations in `dashboard/src/` — each is a type-safety gap (the binary/canvas code is - `any` annotations in `dashboard/src/` — each is a type-safety gap (the binary/canvas code is
exactly where `any` hides bugs). 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]`), 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 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: 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 - 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 - Dashboard/viewer features → `dashboard/src/components|hooks/*` + static HTML
- CI/release deliverables (SPEC-001: versioning, signing, changelog API, gc-feature-request - CI/release deliverables (SPEC-001: versioning, signing, changelog API, gc-feature-request
skill, coord-API) → `.gitea/workflows/*`, `scripts/*`, `.claude/commands/gc-feature-request.md` 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). Use Grep/GrepAI. Cite the exact artifact (file:line, migration name, route path, workflow job).
3. Classify each item: 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 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. doubt → PARTIAL with a note. Bias toward under-flipping.
Return two tables: Return three tables:
`roadmap item | section | current | verdict | proving-or-missing artifact` `roadmap item | section | current | verdict | proving-or-missing artifact`
`debt item | current status | verdict (fixed/open/partial) | artifact` `debt item | current status | verdict (fixed/open/partial) | artifact`
`spec/plan item (SPEC-NNN phase or specs/<slug> 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` | | Feature roadmap | `docs/FEATURE_ROADMAP.md` |
| Tech debt backlog | `TECHNICAL_DEBT.md` (repo root) | | Tech debt backlog | `TECHNICAL_DEBT.md` (repo root) |
| Architecture decisions | `docs/ARCHITECTURE_DECISIONS.md` (ADR-001 RMM↔GC contract, ADR-002 release eng) | | 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/<component>/v*.md`, `CHANGELOG.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` | | Security audits | `SEC{3,4,5}_*_AUDIT.md` / `_COMPLETE.md` |
| Past audit reports | `reports/` (create on first run) | | Past audit reports | `reports/` (create on first run) |