hermes-config/skills/self-hosting/shop-pro-quote/references/roadmap-status-audit.md

# Roadmap Status Audit — SPQ-v2

## When to maintain this

After completing any item in `roadmap_5.2.md` (or any successor roadmap file), **append a dated Master Status Audit section at the bottom of the roadmap file itself**. Ray explicitly asked for this so the next agent can boot up in seconds instead of re-running `search_files`/`read_file` across the whole repo to figure out what's done.

## What it contains

A per-item ✅ / ⚠️ / ❌ / ❓ table for every phase, with **file:line evidence** of the actual current codebase state — not what was planned. Status values:

- ✅ DONE — complete and verified (cite the file/test that proves it)
- ⚠️ PARTIAL — part done (say which part), part blocked (say why, usually `> APPROVAL REQUIRED`)
- ❌ NOT DONE — unstarted; note if approval-gated
- ❓ UNKNOWN — server-side / host-level, not verifiable from the repo

## Format (copy this skeleton)

```markdown
## Master Status Audit — YYYY-MM-DD

> Compiled by an audit pass so the next agent does not burn time re-checking each item.
> Each line records what is actually in the codebase today (verified by search_files / read_file / test run),
> not what was planned.

### Phase N — <Phase Title>

| # | Item | Status | Evidence |
|---|------|--------|----------|
| N.M | <item> | ✅ DONE | `path/file.ts:NN` … |

### Next-item recommendation
<one paragraph: next non-approval, frontend-only, highest-impact item + a pointer to any saved plan in .hermes/plans/>

### Verification snapshot (YYYY-MM-DD)
```
npm run test  → …
npm run build → …
npm run lint  → …
```
```

## How to verify each item efficiently

- `search_files` for the symbol/file the roadmap step says to create (e.g. `ErrorBoundary`, `mutateAssignment`, `quoteWriteSchema`).
- `read_file` the cited file:line to confirm the implementation matches the roadmap spec, not just that the symbol exists.
- `terminal` run `npx vitest run` once for the test-count snapshot; `npm run build` only if code changed this session (prior memos already recorded green builds).
- For PB-migration items: list `pb_migrations/` — absence of the named migration file = ❌ NOT DONE (don't apply without approval).
- **For PB migration items — verify the migration is actually applied in the running container**, not just that the file exists in `pb_migrations/` or in the container's `/pb_data/migrations/`. The proof is:
  ```bash
  docker exec <PB_CID> /usr/local/bin/pocketbase migrate up --dir=/pb_data --migrationsDir=/pb_data/migrations
  ```
  If it says **"No new migrations to apply."** → the migration is live (✅). If it applies a migration → it was on disk but not yet run (⚠️, now applied). Find the container ID with `docker ps --format '{{.ID}} {{.Names}}' | grep pocketbase`.
- **For nginx snippet / security-header items — curl the production URL and grep for headers**:
  ```bash
  curl -sI https://shopproquote.graj-media.com/ | grep -iE 'content-security|x-content|x-frame|referrer|permissions|HTTP/'
  ```
  Snippets can exist on disk (`/etc/nginx/snippets/`) and even be included in the site block but not actually served if the server block wasn't reloaded. The curl check is the source of truth. Run `sudo nginx -t` before relying on config.
- **For systemd-service items — check both the unit file and the running state**:
  ```bash
  systemctl status <service-name> | head -15
  ss -tlnp | grep <port>
  ```
  A unit file on disk doesn't mean the service is enabled or running. `systemctl is-enabled <service>` confirms auto-start.

## Pitfalls

- **Don't trust the "Execution Memo" sections alone** — those record what an agent *claimed* to finish, not what survived. Verify against the codebase. A memo can say "done" while a later refactor reverted it. During the 2026-07-07 Phase 1 audit pass, items 1.2, 1.3, and 1.4 were all already fully implemented on the server but had no Execution Memo and showed ❌/⚠️ in the status table — the code and infrastructure were done, the roadmap just hadn't been updated.
- **"Already done" is a valid outcome** — before writing new code, audit the live state. Items may have been implemented in a prior session without the roadmap being updated. In that case: verify live, flip the status table to ✅, write the Execution Memo, and skip the code work. Do NOT re-implement from the roadmap spec.
- **Approval-gated items stay ❌/⚠️** even if frontend prep is done. The `> APPROVAL REQUIRED` marker in the roadmap text is real — never mark the server half ✅ without the owner's go-ahead (AGENTS.md standing rule).
- **vite.config.ts dev proxy drift**: roadmap 1.2 says point `/deepseek` at `http://127.0.0.1:80`. The live config still targets `https://127.0.0.1:3448` (dead gateway). Ray confirmed on 2026-07-07 he runs **prod only** (nginx/dist, not `npm run dev`), so this fix has zero practical impact and was intentionally skipped. Mark it ⚠️ with a note, not ❌. Do NOT keep re-suggesting this fix every session.
- **`patch` tool parameter gotcha** — the `patch` tool requires `path` (not `patch`) as the parameter name for the file path. Repeated calls with `path` missing hit the tool-call guardrail (5 retries → blocked). If `patch` keeps failing with "path required", switch to `execute_code` with the Python `patch()` wrapper from `hermes_tools`, which takes `path` as a named kwarg and is more forgiving.
- Keep evidence lines terse — `path:line` plus a 6-word fragment. The table is for triage, not prose.

## Current audit location

The live audit lives at the bottom of `/mnt/seagate8tb/Websites/ShopProQuote.backup-20260626-2058/spq-v2/roadmap_5.2.md` (section `## Master Status Audit — 2026-07-07`). Append *new* dated sections below the prior one; don't overwrite old audits — they're a timeline.

## Phase 1 completion (as of 2026-07-07)

All Phase 1 items (1.1–1.7) are ✅ DONE.

## Phase 2 completion (as of 2026-07-07)

All Phase 2 items (2.1–2.10) are ✅ DONE, including 2.7 (logo uploads to PB).

## Phase 3 status (updated 2026-07-07)

| # | Item | Status | Notes |
|---|------|--------|-------|
| 3.1 | GlitchTip self-hosted error tracking | ❌ NOT DONE | Needs go-ahead — Docker stack + @sentry/react + DSN. No /opt/glitchtip exists yet. |
| 3.2 | PocketBase production hardening | ❌ NOT DONE | Needs go-ahead — SMTP env vars on PB container, backup cron, superadmin env. None set currently. |
| 3.3 | Frontend hosting (nginx static) | ✅ ALREADY LIVE | `/etc/nginx/sites-enabled/shopproquote` serves dist/ on 443 with TLS, try_files SPA fallback, security headers. No work needed. |
| 3.4 | Reverse proxy for /pb and /api | ✅ ALREADY LIVE | /pb/ → 127.0.0.1:8091 with WS upgrade + 86400 timeout. /api/ also proxied. No work needed. |
| 3.5 | Structured logging | ❌ NOT DONE | Needs go-ahead — nginx JSON access log format, PB log rotation (json-file driver is set but no rotation limits). |
| 3.6 | Offline banner | ✅ DONE | `src/components/OfflineBanner.tsx` wired in `src/App.tsx` above `<AppRoutes/>`. |
| 3.7 | Dependency audit | ✅ DONE | 0 vulnerabilities. 8 minor/patch updates available (all same-major). No action needed. |

**Key lesson:** Before implementing any Phase 3 item, audit the live nginx config first. 3.3 and 3.4 were already fully deployed via prior sessions with no roadmap update — the roadmap said ❌ but reality said ✅. This mirrors the Phase 1 pattern where 1.2/1.3/1.4 were live but unmarked. Always curl the production URL and inspect the actual server block before writing new config. See `references/spq-v2-deployment.md` for the live nginx layout.

## Phase 4 status (as of 2026-07-07)

All Phase 4 items (4.1–4.10) are ❌ NOT DONE. These are feature items, not infrastructure. Best self-contained picks:
- **4.1** Quote approval notifications (PB hook only, no frontend change) — tiny
- **4.2** Quote expiry enforcement (PB hook + frontend expired UI) — small
- **4.4** Multi-vehicle customer history (new page + route, reuses existing customerId) — most self-contained feature pick
- **4.5** Technician time-card CSV export (new advisor page) — self-contained
- **4.7** Offline-first service worker — scoped as sub-project, significant effort