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.