manage/openspec/changes/grafana-metric-gateway/sync-report.md

Sync Report — grafana-metric-gateway

Phase: sync · Change: grafana-metric-gateway · Repo: /home/user/manage Mode: file-backed (artifactStore: openspec). No source-code edits; only OpenSpec artifacts were written. Not committed (parent owns the commit). The change folder was not moved (that is sdd-archive's job).

Status: SYNCED. The first non-additive canonical sync in the project. The prometheus-charting canonical domain's transport requirements were MODIFIED in place (direct Prom → Grafana gateway), durable behavior requirements were PRESERVED verbatim, and three genuinely new requirements were ADDED (SC-128 … SC-130).

---

1. Executive summary

The prometheus-charting canonical domain (openspec/specs/prometheus-charting/spec.md) was created by prometheus-direct-charting with 27 requirements (SC-101 … SC-127) describing the direct Prometheus transport. The grafana-metric-gateway change switches the prometheus service to a Grafana gateway transport (POST {grafana_url}/api/ds/query), renames the chart/gauge/mean widgets to neutral Metric* components, and validates the gateway path — while preserving the durable behavior contracts (multi-series chart, gauge threshold bands, windowed mean, scalar-only rules).

This sync authored a change-side delta spec with both ## MODIFIED Requirements and ## ADDED Requirements (the project's first delta to use MODIFIED), then applied it to the canonical spec by exact-ID block replacement. No requirements were REMOVED or RENAMED. Verify returned PASS (verdict in verify-report.md: 15 PASS + GM-115 PARTIAL-on-coverage-only, treated as effectively 16/16 per the dispatch brief; apply-progress.md exists and reconciles the 33 task checkboxes the verify report flagged). All five quality gates were green at the verified commits (df80c68, 7e91e7f).

2. Structured status & actionContext findings

The native gentle-pi.sdd-status passed by the parent reports changeName: null / blockedReasons: ["Change selection is ambiguous: grafana-metric-gateway, per-instance-hook-scoping, service-credential-tester."] because the engine auto-detected three active changes. This sync task was explicitly assigned grafana-metric-gateway; the ambiguity is a dispatch artifact and does not block this phase (isNonAuthoritative: false).

• artifactStore: openspec; change root openspec/changes/grafana-metric-gateway/.
• Artifacts present: proposal.md, spec.md (flat, with §"Canonical delta intent" mapping), design.md, tasks.md, verify-report.md, apply-progress.md.
• verify: PASS (verify-report verdict; gates green). The verify report's single CRITICAL was an archive blocker (33 unchecked task checkboxes + missing apply-progress.md); apply-progress.md now exists, and that condition does not block sdd-sync of the green code.
• actionContext: mode: repo-local, workspaceRoot: /home/user/manage, allowedEditRoots: ["/home/user/manage"], warnings: []. All three files written are inside the authoritative workspace / allowed edit roots. ✓
• relationships.sameDomainActiveChanges: [], collisions: [] — no active same-domain collisions, so no archive/sync ordering decision was required.
• The web-ui and service-storage canonical domains were not touched (verified untouched by git status).

3. Domains synced & canonical files updated

Domain	Change-side delta (source)	Canonical (sync target)	Action
prometheus-charting	openspec/changes/grafana-metric-gateway/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

• Canonical file updated: openspec/specs/prometheus-charting/spec.md — now 30 requirements (SC-101 … SC-130).
• Change-side delta created: openspec/changes/grafana-metric-gateway/specs/prometheus-charting/spec.md — ## MODIFIED Requirements (16) + ## ADDED Requirements (3).

4. Requirement delta (MODIFIED / ADDED / PRESERVED)

MODIFIED (16) — transport & naming requirements replaced in place by exact SC- ID

Canonical ID	Header (matched exactly)	What changed (GM source)
SC-101	Prometheus range query returns the existing series shape	direct Prom /api/v1/query_range → Grafana POST /api/ds/query; config base_url → grafana_url+datasource_uid; secret api_key → grafana_api_key (GM-101, GM-102)
SC-102	Series label normalization is shared and Prometheus-native	shared module now holds both normalize_prometheus_matrix + normalize_grafana_frames; shared dedup (GM-104)
SC-103	Range query errors degrade gracefully	gateway-specific failures (401/403, datasource-not-found) added (GM-103)
SC-104	Step is derived from the window preset	step math reused, mapped to intervalMs/maxDataPoints/from-to (GM-105)
SC-105	Chart widget moves from grafana to prometheus	kinds stay on prometheus; transport is gateway; Metric* component binding (GM-109, GM-112)
SC-107	Chart supports multiple series	multi-series via gateway (GM-106)
SC-109	Gauge renders an instant scalar	instant query via gateway (GM-107)
SC-111	Gauge is scalar-only	scalar-only preserved through gateway (GM-107)
SC-112	Mean computes client-side over a window	range query via gateway (GM-108)
SC-114	Mean is scalar-only	scalar-only preserved through gateway (GM-108)
SC-115	No grafana references in backend source	becomes "no grafana service type"; transport refs allowed
SC-116	No grafana references in frontend source	grafana transport allowed; no service type / link widget
SC-121	config.yaml matches implementation	config.yaml now references Grafana as sanctioned transport
SC-122	CHANGELOG documents the migration	migration note → "reconfigure prometheus with gateway fields" (GM-114)
SC-125	New widget kinds have tests	renamed Metric* widgets tested (GM-111)
SC-126	No silent data migration	no auto-migrate of old-shape prometheus config; operator reconfigures (GM-113)

ADDED (3) — fresh canonical IDs continuing the SC- sequence

Canonical ID	Header	GM source
SC-128	get_prometheus_status validates the full gateway path	GM-110
SC-129	Startup logs old-shape prometheus config without crashing	GM-113 (new behavior)
SC-130	Grafana is the sanctioned transport for the prometheus service	sanctioned-transport statement

PRESERVED (11) — unchanged in canonical; NOT in the delta

SC-106 (chart renderer reused), SC-108 (chart window preset), SC-110 (gauge threshold bands), SC-113 (mean plain PromQL), SC-117 (no grafana service type in registries), SC-118 (grafana status/UI removed), SC-119 (orphan degrade), SC-120 (grafana tests removed), SC-123 (backend tests pass), SC-124 (frontend typecheck/build/lint), SC-127 (non-blocking on service-storage-harness).

Count reconciliation: 16 MODIFIED + 11 PRESERVED = 27 pre-existing requirements (SC-101 … SC-127, all retained); + 3 ADDED (SC-128 … SC-130) = 30 total in the canonical spec post-sync.

REMOVED (0) · RENAMED (0)

No requirements were removed or renamed. RENAMED is intentionally unsupported by the native delta helper; the GM→SC mapping was resolved as ADDED/MODIFIED, never RENAMED.

5. Guardrails, approvals & destructive-sync assessment

• Same-domain collisions: none (sameDomainActiveChanges: [], collisions: []). No ordering decision was needed.
• Destructive sync: This is a non-additive (MODIFIED-heavy) sync — 16 MODIFIED blocks, 0 REMOVED. Per the sync contract, a destructive/large-MODIFIED sync requires explicit approval recorded in the parent prompt. Approval is recorded: the dispatch brief explicitly identifies this as "the project's first non-additive sync," enumerates the exact SC-xxx to modify (including the partial ones), and directs the MODIFIED/ADDED/PRESERVED split. No REMOVED requirements are used. Proceeding under that recorded approval.
• MODIFIED-block matching: every MODIFIED block header matched the canonical spec exactly (verified by grep of all 16 headers pre-edit; all 16 replacements applied with zero header mismatches). No ## RENAMED Requirements section was authored.
• Legacy flat spec: the flat spec.md is intentionally left in place as the planning artifact the work was built against (archive convention keeps flat specs); the new domain delta sits alongside it under specs/prometheus-charting/.
• Other-domain isolation: openspec/specs/web-ui/spec.md and openspec/specs/service-storage/spec.md were not modified (git status --porcelain empty for both).

6. Validation / checks performed (file-backed, read-only)

Run from /home/user/manage (no source edits, no test re-runs — owned by verify, already green):

Check	Command	Result
Canonical requirement count	grep -cE "^### Requirement: SC-"	30 ✓ (was 27; +3 ADDED)
Canonical ID sequence intact	grep -oE "SC-[0-9]+" | sort -un	SC-101 … SC-130, contiguous, no gaps/dupes ✓
MODIFIED headers all matched	16 exact-header edits to canonical	all 19 edits applied (front-matter, Purpose, 16 bodies, append) with zero header mismatches ✓
No direct-Prom residue in canonical	grep -c "api/v1/query_range" canonical	1 — and it is SC-101's intentional "MUST NOT issue any direct GET /api/v1/query_range" negation ✓
Preserved block integrity	spot-check SC-106/108/110/113/117/118/127	preserved verbatim ✓
Delta is MODIFIED + ADDED only	count delta section headers	MODIFIED=1, ADDED=1, REMOVED=0, RENAMED=0 ✓ (no REMOVED → no destructive removal)
Delta ADDED IDs are fresh	grep "SC-12[89]|SC-130" delta	SC-128, SC-129, SC-130 ✓ (no GM- reuse in canonical)
web-ui / service-storage untouched	git status --porcelain openspec/specs/{web-ui,service-storage}	empty ✓
Front-matter + Purpose consistent	re-read canonical head	transport narrative updated to gateway (no "no Grafana middleman" contradiction with SC-121/SC-130) ✓
Markdown validity	write-time lint	all three files clean ✓

7. Matching issues

None. All 16 MODIFIED block headers matched the canonical spec exactly; no fallback or fuzzy matching was required. The single api/v1/query_range occurrence in the canonical post-sync is the intentional negation inside SC-101, not a stale direct-Prom requirement.

8. Carry-over / residual notes for the archive summary

1. [COSMETIC, non-blocking] SC-106 (PRESERVED) still reads "preserved in the rebranded PrometheusChartWidget". This change renames that component to MetricChartWidget (GM-111), but SC-106 was explicitly listed as PRESERVED (not MODIFIED) in the change's "Canonical delta intent", so it was left verbatim. The intent (recharts renderer reused unchanged) remains true; only the component name in that one block is a cosmetic carry-over. A future change may refresh the name if desired.
2. [VERIFY carry-over, non-blocking for sync] 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; the dispatch brief treats this as closed/effectively-PASS. The new SC-128 (status gateway path) and SC-129 (startup validation) requirements now canonicalize this behavior; sdd-archive may note the test-coverage gap.
3. [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.
4. [INFO] Stale generated .pi-map.md artifacts still reference old Prometheus*Widget names; not deliverable source — regenerate at the orchestrator's convenience.
5. [INFO] Two uncommitted whitespace-only edits exist in the working tree (PrometheusMetricWidget.tsx, ServicesPage.tsx) — unrelated to this sync; no files were staged by this phase (git diff --cached empty).

9. Next recommended phase

→ sdd-archive (clean). Re-scan the native status engine to confirm specs: done / sync: ready / archive: ready, then move the change to openspec/changes/archive/YYYY-MM-DD-grafana-metric-gateway, carrying over the items in §8. Do not commit or push — the parent owns the commit with explicit paths.

---

Appendix — Files written by this sync (OpenSpec only; no source code)

• openspec/changes/grafana-metric-gateway/specs/prometheus-charting/spec.md — change-side domain delta (## MODIFIED Requirements × 16 + ## ADDED Requirements × 3).
• openspec/specs/prometheus-charting/spec.md — canonical spec (MODIFIED × 16 in place, ADDED × 3 appended; now 30 requirements SC-101 … SC-130; front-matter + Purpose updated for transport consistency).
• openspec/changes/grafana-metric-gateway/sync-report.md — this report.