From d0cab6a57f924d612290f3c3970f4037e9f46a86 Mon Sep 17 00:00:00 2001
From: Andrei Taranik <andrey@cicd.team>
Date: Sat, 23 May 2026 10:58:50 +0300
Subject: [PATCH] docs: drop dead spec-section pointers from public files +
 code comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The design spec lives under .claude/docs/superpowers/specs/, which is
gitignored. Citations like "see spec §5.5" or "(§6.3)" are dead pointers
for anyone reading the codebase outside the original author's local
workstation. Replaced each with the concrete concept the section
described:

- README.md:159 - "spec §5.5" -> "envelope (target, overview, findings,
  warnings)"
- internal/output/json/json.go - "§5.5 schema" -> explicit field list
- internal/cli/render.go - "§5.5 envelope" -> "Report envelope"
- internal/findings/severity.go - "JSON schema in the spec (§5.5)" ->
  "lower-case string (critical|high|medium|low) for the public JSON
  wire form"
- internal/analyzers/labelpattern/patterns.go - "spec (§6.3)" ->
  "high-cardinality label-name patterns the analyzer flags by default"

No behavior change; comment-only.
---
 README.md                                   | 4 ++--
 internal/analyzers/labelpattern/patterns.go | 4 ++--
 internal/cli/render.go                      | 2 +-
 internal/findings/severity.go               | 4 ++--
 internal/output/json/json.go                | 3 ++-
 5 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d8ee492..ccba27f 100644
--- a/README.md
+++ b/README.md
@@ -156,8 +156,8 @@ remetric scan \
   --grafana http://localhost:3000
 ```
 
-`scan` emits a `findings.Report` (see spec §5.5) - combine with `--output json`
-for CI.
+`scan` emits a `findings.Report` envelope (target, overview, findings,
+warnings) - combine with `--output json` for CI.
 
 ## VictoriaMetrics support
 
diff --git a/internal/analyzers/labelpattern/patterns.go b/internal/analyzers/labelpattern/patterns.go
index 3fc0b2d..fe34d45 100644
--- a/internal/analyzers/labelpattern/patterns.go
+++ b/internal/analyzers/labelpattern/patterns.go
@@ -7,8 +7,8 @@ package labelpattern
 
 import "regexp"
 
-// defaultPatternSources are the verbatim regex patterns from the spec
-// (§6.3). Compiled lazily via DefaultPatterns.
+// defaultPatternSources are the high-cardinality label-name patterns
+// the analyzer flags by default. Compiled lazily via DefaultPatterns.
 var defaultPatternSources = []string{
 	`(?i).*(uuid|guid).*`,
 	`(?i).*_id$`,
diff --git a/internal/cli/render.go b/internal/cli/render.go
index bca6c13..f4c838f 100644
--- a/internal/cli/render.go
+++ b/internal/cli/render.go
@@ -51,7 +51,7 @@ func validateOutput(s string) error {
 
 // renderReport dispatches Report rendering based on cfg.Output.
 // Terminal output prints any Warnings as a yellow banner above the
-// findings table. JSON emits the full §5.5 envelope.
+// findings table. JSON emits the full Report envelope.
 //
 // renderReport populates Finding.DocURL from Finding.Class for every
 // finding in rep that has a Class but no caller-provided DocURL. The fill
diff --git a/internal/findings/severity.go b/internal/findings/severity.go
index f77c10c..068bda8 100644
--- a/internal/findings/severity.go
+++ b/internal/findings/severity.go
@@ -57,8 +57,8 @@ func ParseSeverity(s string) (Severity, error) {
 	return 0, fmt.Errorf("unknown severity %q", s)
 }
 
-// MarshalJSON encodes the severity as a lower-case string,
-// matching the JSON schema in the spec (§5.5).
+// MarshalJSON encodes the severity as a lower-case string
+// (critical|high|medium|low) for the public JSON wire form.
 func (s Severity) MarshalJSON() ([]byte, error) {
 	return json.Marshal(s.lower())
 }
diff --git a/internal/output/json/json.go b/internal/output/json/json.go
index 86f1bc0..0d90a6d 100644
--- a/internal/output/json/json.go
+++ b/internal/output/json/json.go
@@ -45,7 +45,8 @@ func (r *Renderer) RenderFindingsWithIgnored(fs []findings.Finding, ignored int)
 	return r.encode(envelope)
 }
 
-// RenderReport emits the full §5.5 schema.
+// RenderReport emits the full Report envelope (target, overview,
+// findings, warnings, ignored_count, scanned_at).
 func (r *Renderer) RenderReport(rep *findings.Report) error {
 	if rep == nil {
 		return fmt.Errorf("output/json: nil report")