From 9236fd8ac2c08d6848be9fd56d79027594e9b8df Mon Sep 17 00:00:00 2001 From: Developer Date: Thu, 9 Jul 2026 22:06:43 +0000 Subject: [PATCH] chore(grafana-metric-gateway): archive verified+synced change Move to openspec/changes/archive/2026-07-09-grafana-metric-gateway/ (R100 renames preserved). 9 artifacts. Canonical openspec/specs/ prometheus-charting/ (30 reqs, first non-additive sync) remains. Carry-overs in archive-report: SC-106 stale component name (cosmetic); partial revert of prometheus-direct-charting per new network constraint. --- .../apply-progress.md | 0 .../archive-report.md | 233 ++++++++++++++++++ .../design.md | 0 .../proposal.md | 0 .../spec.md | 0 .../specs/prometheus-charting/spec.md | 0 .../sync-report.md | 0 .../tasks.md | 0 .../verify-report.md | 0 9 files changed, 233 insertions(+) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/apply-progress.md (100%) create mode 100644 openspec/changes/archive/2026-07-09-grafana-metric-gateway/archive-report.md rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/design.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/proposal.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/spec.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/specs/prometheus-charting/spec.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/sync-report.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/tasks.md (100%) rename openspec/changes/{grafana-metric-gateway => archive/2026-07-09-grafana-metric-gateway}/verify-report.md (100%) diff --git a/openspec/changes/grafana-metric-gateway/apply-progress.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/apply-progress.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/apply-progress.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/apply-progress.md diff --git a/openspec/changes/archive/2026-07-09-grafana-metric-gateway/archive-report.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/archive-report.md new file mode 100644 index 0000000..ee171a4 --- /dev/null +++ b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/archive-report.md @@ -0,0 +1,233 @@ +# 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. diff --git a/openspec/changes/grafana-metric-gateway/design.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/design.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/design.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/design.md diff --git a/openspec/changes/grafana-metric-gateway/proposal.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/proposal.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/proposal.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/proposal.md diff --git a/openspec/changes/grafana-metric-gateway/spec.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/spec.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/spec.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/spec.md diff --git a/openspec/changes/grafana-metric-gateway/specs/prometheus-charting/spec.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/specs/prometheus-charting/spec.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/specs/prometheus-charting/spec.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/specs/prometheus-charting/spec.md diff --git a/openspec/changes/grafana-metric-gateway/sync-report.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/sync-report.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/sync-report.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/sync-report.md diff --git a/openspec/changes/grafana-metric-gateway/tasks.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/tasks.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/tasks.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/tasks.md diff --git a/openspec/changes/grafana-metric-gateway/verify-report.md b/openspec/changes/archive/2026-07-09-grafana-metric-gateway/verify-report.md similarity index 100% rename from openspec/changes/grafana-metric-gateway/verify-report.md rename to openspec/changes/archive/2026-07-09-grafana-metric-gateway/verify-report.md