manage/openspec/changes/archive/2026-07-09-grafana-metric-gateway/archive-report.md

# Archive Report — `grafana-metric-gateway`

> Phase: **archive** · Change: `grafana-metric-gateway` · Repo: `/home/user/manage`
> Mode: file-backed (`artifactStore: openspec`). No source-code edits; only OpenSpec artifacts
> were touched. **Not committed** — the parent/orchestrator owns the archive commit. No push, no `gh`.

**Status: ARCHIVED.** All eight lifecycle phases are complete (proposal → spec → design → tasks →
apply → verify → sync → **archive**). Every archive precondition is verified PASS (see §2). The
canonical `openspec/specs/prometheus-charting/spec.md` (updated by `sdd-sync` with the project's
first non-additive delta — 16 MODIFIED + 3 ADDED) remains in place as the durable end-state spec and
is **not** moved (archive never moves canonical specs). The change folder was moved to
`openspec/changes/archive/2026-07-09-grafana-metric-gateway/` via `git mv` to preserve history.

---

## 0. Archive disposition

- **Disposition: `archived`.** The parent explicitly requested the `git mv` and owns the commit, so
  the move is executed here and left staged for the parent's explicit-path commit.
- **Archive convention:** OpenSpec SDD archive contract for `openspec` mode — completed file-backed
  sync → write the in-folder archive report → move the change folder to
  `openspec/changes/archive/YYYY-MM-DD-{change}/`. No standalone manifest/index exists under
  `openspec/` (only `config.yaml`, `changes/`, `specs/`), so the folder move **is** the archive
  mechanism. No `rules.archive` override exists in `openspec/config.yaml`.
- **Target archived path:** `openspec/changes/archive/2026-07-09-grafana-metric-gateway/`
- **Archive date:** `2026-07-09` (ISO).
- **Canonical spec left in place (not moved):** `openspec/specs/prometheus-charting/spec.md` —
  30 requirements (SC-101 … SC-130). Verified present and untouched after the move.
- **`openspec/specs/web-ui/spec.md` and `openspec/specs/service-storage/spec.md` also left
  untouched** (the other canonical domains).
- **Audit-trail integrity:** the change folder was moved as a whole, including the legacy flat
  `spec.md`, the per-domain delta `specs/prometheus-charting/spec.md`, `apply-progress.md`,
  `verify-report.md`, and `sync-report.md`, which travel with the record. Nothing was silently
  deleted or rewritten.

## 1. Native `sdd-status` read & discrepancy statement

The native `gentle-pi.sdd-status` engine supplied by the parent reports **non-actionable state for
this archive** because it was resolved without a change context: `changeName: null`,
`artifacts: all missing`, `applyState: blocked`, `dependencies.archive: blocked`,
`blockedReasons: ["Change selection is ambiguous: grafana-metric-gateway, per-instance-hook-scoping,
service-credential-tester."]`, `isNonAuthoritative: false`. This is a **parent-resolution artifact**:
the engine auto-detected three active changes and could not pick one. The ambiguity does **not**
reflect the state of `grafana-metric-gateway`, which this archive task was **explicitly assigned**.

**Discrepancy with the parent's authoritative confirmed state — RESOLVED in favor of the parent.**
The parent physically verified (and this executor re-confirmed directly against the filesystem in
§2) that all 33 tasks are ticked, `apply-progress.md` exists and records the work, the verify report
confirms functional completion, and the sync report confirms a SYNCED canonical domain. Per the
archive contract's non-authoritative-store carve-out guidance and the parent's explicit instruction,
the stale `archive: blocked` / "ambiguous" labels are **disregarded** and the archive **proceeds**.

Direct filesystem re-validation (§2) is the source of truth for this report.

## 2. Archive preconditions (validated directly against the filesystem)

| Precondition | Evidence | Result |
|---|---|---|
| Verify report present | `verify-report.md` | ✓ verdict **PASS** (functionally complete) |
| Verify clearly passing — no unresolved `FAIL`/`BLOCKED`/`CRITICAL` | the sole CRITICAL was a reconcilable task-hygiene gap (33 unchecked boxes + missing `apply-progress.md`), now **resolved**; GM-115 was PARTIAL on enumerated test-coverage only (non-critical), treated as closed per parent confirmation (15/16 PASS → 16/16) | ✓ |
| Sync report present & successful | `sync-report.md` → **Status: SYNCED** | ✓ |
| Canonical spec exists (sync target, updated) | `openspec/specs/prometheus-charting/spec.md` (30 requirements, SC-101 … SC-130) | ✓ |
| Change-side domain delta exists | `specs/prometheus-charting/spec.md` (16 MODIFIED + 3 ADDED) | ✓ |
| Delta op-class = non-additive (MODIFIED + ADDED; no REMOVED) | MODIFIED=16, ADDED=3, REMOVED=0, RENAMED=0 | ✓ |
| Requirement-ID parity | canonical 30 = 27 retained + 3 ADDED; contiguous SC-101 … SC-130, no gaps/dupes | ✓ |
| proposal / design / tasks artifacts present | all populated | ✓ |
| **Final Task Completion Gate — zero unchecked `- [ ]`** | `grep -nE '^\s*- \[ \]' tasks.md` → **NONE**; `grep -cE '^\s*- \[x\]'` → **33** | ✓ |
| `apply-progress.md` present & records the work | present; status "complete — all 33 tasks done", 2 slices documented | ✓ |
| No active same-domain (`prometheus-charting`) collision | `sameDomainActiveChanges: []`, `collisions: []` (per sync-report §2); only this change carries a `prometheus-charting` delta | ✓ |

**Stale-checkbox reconciliation note.** At verify time, all 33 implementation/verification checkboxes
(Slice 1 §1.1–1.16, Slice 2 §2.1–2.11, Integration §3.1–3.6) were unchecked and `apply-progress.md`
did not exist. That condition was reconciled **before** archive: the boxes are now all ticked and
`apply-progress.md` was authored documenting the two landed slices (`df80c68`, `7e91e7f`) and the
gate results. `apply-progress.md` plus the verify report prove every previously-unchecked task
complete. No archive-time mechanical checkbox repair was needed — the gate now passes on the
persisted `tasks.md` as-is. No partial-archive approval applies.

## 3. Artifacts read (archive preflight)

- `openspec/changes/grafana-metric-gateway/proposal.md`
- `openspec/changes/grafana-metric-gateway/spec.md` (flat, authoritative planning artifact — 16 requirements GM-101 … GM-116)
- `openspec/changes/grafana-metric-gateway/specs/prometheus-charting/spec.md` (change-side domain delta)
- `openspec/changes/grafana-metric-gateway/design.md`
- `openspec/changes/grafana-metric-gateway/tasks.md`
- `openspec/changes/grafana-metric-gateway/apply-progress.md`
- `openspec/changes/grafana-metric-gateway/verify-report.md`
- `openspec/changes/grafana-metric-gateway/sync-report.md`
- `openspec/specs/prometheus-charting/spec.md` (canonical, sync target — verified present and untouched)
- `openspec/config.yaml` (rules: proposal/tasks; no `rules.archive` override)
- House-style reference: `openspec/changes/archive/2026-07-08-prometheus-direct-charting/archive-report.md`

> The legacy flat `spec.md` is **not** the only spec artifact: a per-domain delta
> (`specs/prometheus-charting/spec.md`) and a canonical spec both exist, so the "legacy flat spec
> as the *only* artifact" archive-block condition does not apply. The flat spec travels with the
> archived folder as part of the audit trail.

## 4. Domains synced & requirement delta

| Domain | Change-side delta | Canonical | Action |
|---|---|---|---|
| `prometheus-charting` | `specs/prometheus-charting/spec.md` | `openspec/specs/prometheus-charting/spec.md` | **MODIFIED + ADDED** — 16 requirement blocks replaced in place by exact ID; 3 new requirements appended |

- **MODIFIED (16)** — transport & naming requirements replaced in place by exact SC- ID: SC-101,
  SC-102, SC-103, SC-104, SC-105, SC-107, SC-109, SC-111, SC-112, SC-114, SC-115, SC-116, SC-121,
  SC-122, SC-125, SC-126. These switch the data source from direct Prom (`/api/v1/query[_range]`) to
  the Grafana `POST /api/ds/query` gateway, and re-scope the "no grafana references" requirements to
  "no grafana **service type**" (transport refs now allowed).
- **ADDED (3)** — fresh canonical IDs continuing the SC- sequence: SC-128 (`get_prometheus_status`
  validates the full gateway path), SC-129 (startup logs old-shape prometheus config without
  crashing), SC-130 (Grafana is the sanctioned transport for the prometheus service).
- **PRESERVED (11)** — unchanged in canonical, not in the delta: SC-106, SC-108, SC-110, SC-113,
  SC-117, SC-118, SC-119, SC-120, SC-123, SC-124, SC-127.
- **REMOVED (0)** · **RENAMED (0)** — nothing destructive.

> **This is the project's first non-additive canonical sync.** The MODIFIED-heavy delta was approved
> in the parent dispatch (explicitly identified as "the project's first non-additive sync," with the
> exact SC-xxx to modify enumerated). See §7.

## 5. Final lifecycle status (all 8 phases done)

| Phase | Status | Evidence |
|---|---|---|
| Proposal | ✅ done | `proposal.md` |
| Spec | ✅ done | flat `spec.md` (16) + domain delta `specs/prometheus-charting/spec.md` (16 MODIFIED + 3 ADDED) |
| Design | ✅ done | `design.md` |
| Tasks | ✅ done | `tasks.md` — **33/33** checked, zero `- [ ]` |
| Apply | ✅ done | 2 slices delivered (commits `df80c68` slice-1 backend, `7e91e7f` slice-2 frontend renames) |
| Verify | ✅ PASS | `verify-report.md` — 15/16 PASS, GM-115 PARTIAL-on-coverage (closed per parent; effectively 16/16); gates green |
| Sync | ✅ done | `sync-report.md` — SYNCED; canonical `prometheus-charting` domain MODIFIED + ADDED (now 30 requirements) |
| Archive | ✅ done | this report + folder move performed |

## 6. Gate results (per verify-report / apply-progress)

| Gate | Command | Result |
|---|---|---|
| Backend tests | `cd backend && PYTHONPATH=src python3 -m pytest -q` | **PASS** — 331 passed (2 pre-existing warnings) |
| Backend lint | `cd backend && PYTHONPATH=src python3 -m ruff check src tests` | **PASS** — All checks passed |
| Frontend build | `cd frontend && npm run build` | **PASS** — exit 0 (pre-existing chunk-size advisory) |
| Frontend lint | `cd frontend && npm run lint` | **PASS** — 0 errors (1 pre-existing unrelated warning) |
| Frontend tests | `cd frontend && npx vitest run` | **PASS** — 151 passed / 44 files |

## 7. Carry-over follow-ups & non-blocking notes (recorded for the record)

1. **[COSMETIC — deferred fix]** **Preserved SC-106 still names `PrometheusChartWidget`.** SC-106 was
   explicitly listed as **PRESERVED** (not MODIFIED) in this change's "Canonical delta intent", so it
   was left verbatim in the canonical spec. It reads: *"…preserved in the rebranded
   `PrometheusChartWidget`."* This change **renames** that component to `MetricChartWidget` (GM-111),
   so the component name in that one canonical block is now stale. The *intent* — recharts renderer
   (line chart, multi-series, axes, tooltip, `mergeSeries`, color tokens) reused unchanged — remains
   true. This is purely a cosmetic carry-over; a future change may refresh the name if desired. Not
   blocking.
2. **[INFO — first non-additive sync]** **The first non-additive canonical sync is complete.** 16
   MODIFIED + 3 ADDED + 0 REMOVED were applied to `openspec/specs/prometheus-charting/spec.md` by
   exact-ID block replacement. All 16 MODIFIED headers matched the canonical spec exactly (zero
   mismatches); the canonical spec now has 30 requirements (SC-101 … SC-130, contiguous). No
   destructive REMOVED requirements were used, so no destructive-removal guard was triggered. The
   MODIFIED-heavy delta was approved in the parent dispatch.
3. **[INFO — partial revert of `prometheus-direct-charting`]** **This change partially reverts the
   archived `prometheus-direct-charting` (2026-07-08).** A new network constraint surfaced after
   `prometheus-direct-charting` shipped: the Prometheus instance is **not directly reachable** from
   the Manage backend (firewalled / different network / no auth proxy); Grafana is the only reachable
   surface. This change undoes that change's direct-Prom transport and Grafana **removal** (re-routing
   all metric queries through Grafana's `POST /api/ds/query` datasource proxy, restoring the
   `normalize_grafana_frames` normalizer recovered from git commit `65bae95`), while **preserving**
   its durable gauge/mean/`LineSeriesChart`/rendering work. It is a justified reversal based on new
   information, not a fourth flip of preference. The canonical `prometheus-charting` domain now
   reflects the gateway transport (Grafana = transport; Prometheus = logical source). The
   `prometheus` service type remains the sole metric surface — **no `grafana` service type is
   reintroduced**.
4. **[VERIFY carry-over]** GM-115 was PARTIAL in verify on enumerated test-coverage only (no
   startup-validation test; no status 401/403 → `auth_failed` test). Functional code is correct and
   green; the parent confirmed this as closed (effectively 16/16). The new SC-128 (status gateway
   path) and SC-129 (startup validation) canonicalize this behavior; two small follow-up tests may be
   added in a future change.
5. **[INFO]** `normalize_prometheus_matrix` is intentionally retained as dead production code
   (future-proof for a possible `direct_url` path); canonicalized by the MODIFIED SC-102.
6. **[INFO]** Stale generated `.pi-map.md` artifacts still reference old `Prometheus*Widget` names;
   not deliverable source (ignored by tsc/vite/eslint) — regenerate via
   `project_map_patch`/`project_map_validate` at the orchestrator's convenience. **Not touched by
   this archive.**
7. **[INFO]** The working tree carries unrelated dirty/untracked items **not owned by this archive**:
   a whitespace-only uncommitted modification to `frontend/src/pages/ServicesPage.tsx` (predating/
   orthogonal to this change) and untracked `.pi-tmp/*` scratch files (other-change strays). Per
   discipline these were **left untouched**.

## 8. Residual risks & destructive-merge statement

- **Destructive sync / merge:** **none destructive.** Zero REMOVED requirements; the 16 MODIFIED
  blocks replaced transport/naming requirements in place by exact ID with the durable behavior
  preserved. The MODIFIED-heavy non-additive delta was approved in the parent dispatch (explicit
  "first non-additive sync" identification + enumerated SC-xxx). No destructive-removal guard was
  triggered.
- **Backend / data-contract impact:** none new beyond the documented operator migration. All
  Prometheus metric queries are gated behind Grafana's `/api/ds/query` with **zero** direct-Prom HTTP
  residue in `widgets/sources.py`. Old-shape `prometheus` services (with `base_url`) warn on startup
  and return `grafana_url is required` errors until reconfigured — the intended degraded state, with
  the required operator action documented in the CHANGELOG. The `{series}` / `{value}` widget data
  shapes are preserved. Archive touched only OpenSpec docs + the folder move.
- **No critical verification issues** remain (CRITICAL issues are non-overridable; the one verify
  CRITICAL was the reconcilable checkbox/apply-progress gap, now resolved).
- **No browser/visual smoke** was performed (out of scope); recharts rendering is structurally
  tested only.
- **Memory observation IDs:** none — `artifactStore: openspec`; traceability lives in the filesystem
  archive + canonical spec.

## 9. Move performed

```
git mv openspec/changes/grafana-metric-gateway openspec/changes/archive/2026-07-09-grafana-metric-gateway
```

- **All 9 artifacts confirmed present at the archived path:** `proposal.md`, `spec.md`,
  `specs/prometheus-charting/spec.md` (delta), `design.md`, `tasks.md`, `apply-progress.md`,
  `verify-report.md`, `sync-report.md`, `archive-report.md` (this file).
- **Canonical `openspec/specs/prometheus-charting/spec.md` remains in place** (verified untouched
  after the move). `openspec/specs/web-ui/spec.md` and `openspec/specs/service-storage/spec.md` also
  untouched.
- Renames were left **staged** (R100 detection preserved) for the parent's explicit-path commit.
  `git restore --staged` was **not** run after the `git mv` (a prior archive agent did so and
  discarded rename detection).

---

### Appendix — Files written/moved by this archive (OpenSpec only; no source code)

- **Written:** `openspec/changes/grafana-metric-gateway/archive-report.md` (this file) — at the
  active path before the move; travels with the move into the archive.
- **Moved (via `git mv`):** the entire
  `openspec/changes/grafana-metric-gateway/` directory →
  `openspec/changes/archive/2026-07-09-grafana-metric-gateway/`.
- **Left in place (durable canonical):** `openspec/specs/prometheus-charting/spec.md`.
- **Not committed / not pushed** — the parent owns the commit with explicit paths.