Sanitized Diagnostic Bundle & Issue Reporting CLI Specification

1. Executive Summary & Problem Statement#

Open-core adopters reporting defects need one command to capture runtime context (Nomos, Go, OS, Git, phase, worktree, and SQLite health). That collector must never leak personal filesystem paths, GitHub PATs, API keys, or bearer credentials into public issue trackers.

This specification codifies nomos issue (substrate/cli/cmd_issue.go), the cli.IssueReport contract, deterministic credential and path scrubbing, and fail-closed browser dispatch. nomos issue provides a zero-dependency, client-side diagnostic collector that scrubs sensitive strings deterministically before previewing (--dry-run) or opening a pre-filled GitHub issue URL.

---

2. Axiomatic Invariants & Governing Laws#

Law #	Law Name	Architectural Invariant	Machine Enforcement Mechanism
1	The Dual-Core Inversion Law	Go runtime and Git state collect diagnostic telemetry without LLM summarization.	collectIssueReport
2	The Non-Verbal Proof Law	Bug bundles attach verified NomosVersion, GoVersion, GitVersion, ActivePhase, and DatabaseStatus.	formatIssueMarkdown (Cell 2.1 (tdd))
4	The Single Source of Truth Law	Diagnostic bundle fields bind 1:1 to cli.IssueReport in substrate/cli/cmd_issue.go.	cmd_issue_test.go & Go compiler
5	The Zero-Hardcoded-Path Law	sanitizeText scrubs os.UserHomeDir() paths to ~ before output or URL encoding.	sanitizeText (Cell 5.1 (forbidden_literals))
6	The Canonical Singularity Law	nomos issue registers as the sole bug-report command on NewRootCmd().	Cell 6.2 (zero_alias), Cell 2.1 (dead_code)
7	The Fail-Closed Pre-Flight Law	openBrowser rejects non-GitHub URLs and prompts unless --yes or --dry-run applies.	openBrowser URL prefix guard (Cell 7.1 (secret))

---

3. Compiled Go SSoT Contract (substrate/cli/cmd_issue.go)#

Compiled Go structures and command constructors in substrate/cli/cmd_issue.go define the diagnostic payload and dispatch surface:

package cli

import "github.com/spf13/cobra"

// IssueReport holds the collected and sanitized diagnostic bundle (#IssueReport).
type IssueReport struct {
	Title          string
	Description    string
	NomosVersion   string
	GoVersion      string
	Platform       string
	GitVersion     string
	ActivePhase    string
	ActiveBranch   string
	IsWorktree     bool
	DatabaseStatus string
}

// NewIssueCmd constructs the canonical 'nomos issue' command.
func NewIssueCmd() *cobra.Command

---

4. Deterministic Secret & Path Scrubbing (sanitizeText)#

Before populating #IssueReport.Title or #IssueReport.Description, sanitizeText applies five ordered transformations:

1. Home Path Redaction: Replaces os.UserHomeDir() occurrences with ~.
2. GitHub Token Redaction: Scrubs ghp_* and github_pat_* tokens to [REDACTED_GH_TOKEN].
3. API Key Redaction: Scrubs sk-* secret keys to [REDACTED_API_KEY].
4. Bearer Header Redaction: Scrubs Bearer <token> headers (case-insensitive) to Bearer [REDACTED].
5. Authenticated URL Redaction: Scrubs http(s)://<user>:<pass>@ basic-auth credentials to http(s)://user:[REDACTED]@.

---

5. CLI Command Syntax & Flags (substrate/cli/cmd_issue.go)#

nomos issue [title] [--dry-run] [--web|-w] [--yes|-y] [--body|-b <text>]

Flag	Shorthand	Default	Semantics
--dry-run	-	false	Prints sanitized Markdown and GitHub URL to stdout without browser launch.
--web	-w	true	Opens the pre-filled GitHub URL via xdg-open, open, or rundll32.
--yes	-y	false	Skips interactive [y/N] confirmation when launching the browser in a TTY.
--body	-b	""	Supplies reproduction details or error diagnostics passed automatically through sanitizeText.

---

6. Table-Driven Verification Vectors#

Vector ID	Scenario	Input Vector	Expected Verdict	Invariant Verified
TC-ISS-01	Dry-Run Preview	nomos issue "Gate edge case" --dry-run	Prints sanitized Markdown payload and https://github.com/mgantlett/nomos/issues/new?... without opening browser	Law 2 & Law 6
TC-ISS-02	Credential Scrubbing	--body containing a ghp_<20+char> PAT and sk-<20+char> key	Emits [REDACTED_GH_TOKEN] and [REDACTED_API_KEY] with zero raw secrets	Law 5 & Law 7
TC-ISS-03	URL Prefix Guard	openBrowser("https://example.com/phish")	Fails closed (refusing to open non-GitHub URL)	Law 7 (Fail-Closed)

---

7. Cross-Plane Traceability & DoD Verification#

Component	Substrate SSoT Path	Canonical 7x3 Cell
Issue Diagnostic Collector	substrate/cli/cmd_issue.go	Cell 6.2 (zero_alias), Cell 2.1 (dead_code)
Issue Scrubbing Test Suite	substrate/cli/cmd_issue_test.go	Cell 2.1 (tdd), Cell 2.2 (coverage)
Root Cobra Registration	substrate/cli/root.go	Cell 6.2 (zero_alias)
Secret & Literal Guards	substrate/src/nomos/modules/verify/gates_security.go	Cell 7.1 (secret), Cell 5.1 (forbidden_literals)

Deterministic verification executes via nomos verify and passes all 42 Definition of Done quality gates with exit code 0.