Cleanup 418 (v5): revert broken Copilot autofixes, restore green CI

[jpoley]

Summary

Replaces closed PR #1245. Same cleanup-418 branch. Three Copilot autofix commits were pushed to #1245 on top of my caching fix, and two of them broke CI. This PR reverts the two broken ones, keeps the benign one, and restores all checks to green locally.

What broke on #1245

Four CI jobs went red: lint (format), test, validate-dev-role, validate-qa-role. Root causes were two Copilot autofix commits.

Reverted: d08b27a — hallucinated kwargs in setup_command

The autofix changed two calls in src/flowspec_cli/gpg_cli.py:

fingerprint = generate_agent_key(fingerprint=existing_fingerprint)
configure_git_signing(project_root=root, fingerprint=fingerprint)

Neither function accepts a fingerprint kwarg:

Function	Signature (src/flowspec_cli/signing.py)
generate_agent_key	line 99 — def generate_agent_key() -> str
configure_git_signing	line 166 — def configure_git_signing(project_root: Optional[Path] = None) -> None

Both calls would raise TypeError at runtime the first time anyone ran flowspec gpg setup. That's what took down the test / validate-*-role jobs.

Reverted: 48d2134 — duplicate safety + format drift in rotate_command

The autofix added a post-delete keyring re-read:

delete_agent_key()
remaining_fingerprint = get_key_fingerprint()
if remaining_fingerprint == old_fingerprint:
    raise GPGConfigurationError("Failed to delete the existing agent GPG key.")

Three problems:

1. delete_agent_key() already raises GPGError if either the gpg --delete-secret-and-public-key call or the keyring.delete_password call fails (signing.py:349-356). This verification is duplicate safety.
2. The extra keyring read is exactly the pattern PRs Cleanup 418 (v3): doctor + GPG signing, with Copilot caching fix #1244/Cleanup 418 (v4): finish keyring-read caching + subprocess timeouts #1245 set out to eliminate, and it breaks TestRotateCommandKeyringReads::test_reads_fingerprint_once_when_rotating.
3. The new block also left gpg_cli.py failing ruff format --check — that was the lint failure.

Kept: 9a76497 — benign doctor.py refactor

Splits (result.stdout or result.stderr).strip() into two separate .strip() calls. Semantically unchanged. No reason to revert.

Validation

• uv run ruff format --check . — 324 files clean
• uv run ruff check . — all checks passed
• uv run pytest tests/ -x -q — 3544 passed, 42 skipped
• CI green on this PR
• All commits in this PR are DCO-signed (git commit -s)

A note on the Copilot autofix findings

Both reverted commits were titled "Potential fix for pull request finding" — the autofix responded to some security/CodeQL advisory on #1245. The advisory scan was flagged as advisory, not blocking in the original comment. The proposed "fixes" were incorrect (see above); the underlying concern they were aimed at (keyring reads / delete verification) is already handled:

• Keyring reads at the CLI layer are cached to exactly one per invocation (see Cleanup 418 (v4): finish keyring-read caching + subprocess timeouts #1245 commit f203a82).
• Delete failure is already raised by delete_agent_key() itself.

If the same advisory re-appears on this PR, the right follow-up is to add a real fingerprint kwarg to generate_agent_key / configure_git_signing in signing.py first, then wire it through — not to push call-site code that doesn't match the API.

🤖 Generated with Claude Code

[github-actions]

🟢 Security Scan Results (Advisory)

Note: Security scanning is advisory and does not block PR merges.

• Total Findings: 11
• Critical: 0
• High: 0

No critical or high severity issues found.

How to remediate

# View detailed scan results
gh run download 24640329044 -n security-scan-results-ac4a8776a345a4a571878b8eb09e8c27acbee7d2

# Triage findings with AI assistance
specify security triage

# Generate fix suggestions
specify security fix

# Apply fixes and re-scan
flowspec security scan

See the Security tab for detailed findings.

[Copilot]

Pull request overview

This PR restores green CI after incorrect automated “autofix” changes by ensuring the flowspec gpg commands align with the signing API and by re-establishing the “avoid redundant keyring reads” behavior and its regression coverage.

Changes:

• Adds/updates GPG signing primitives and Typer subcommands (gpg setup/status/rotate) and wires the gpg and doctor commands into the main CLI.
• Adds extensive regression tests for GPG signing/keyring-read behavior and doctor subprocess timeouts.
• Updates documentation (new GPG signing guide) and rewrites README; removes several .claude/commands/* documents.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/flowspec_cli/signing.py	GPG/keyring/git-signing primitives, including cached-fingerprint support in get_key_info.
src/flowspec_cli/gpg_cli.py	Implements flowspec gpg setup/status/rotate with caching commentary and Rich output.
src/flowspec_cli/doctor.py	Implements doctor checks + subprocess version-probe timeouts.
src/flowspec_cli/__init__.py	Registers gpg sub-app and adds doctor command to the main CLI.
tests/test_signing.py	Unit tests for signing primitives and keyring behavior.
tests/test_gpg_cli.py	CLI-level regression tests for avoiding redundant get_key_fingerprint() reads.
tests/test_doctor.py	Regression tests ensuring tool version probes are time-bounded.
docs/guides/gpg-signing.md	New end-user guide for agent GPG signing setup, status, and rotation.
README.md	Substantial rewrite of product messaging and command documentation.
.claude/commands/vibe/vibe.md	Removes repo-local vibe command doc.
.claude/commands/flow/security_workflow.md	Removes repo-local security workflow doc.
.claude/commands/flow/security_web.md	Removes repo-local security web doc.
.claude/commands/flow/security_triage.md	Removes repo-local security triage doc.
.claude/commands/flow/security_report.md	Removes repo-local security report doc.
.claude/commands/flow/security_fix.md	Removes repo-local security fix doc.
.claude/commands/flow/intake.md	Removes repo-local intake command doc.
.claude/commands/flow/custom.md	Removes repo-local custom workflow command doc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

test_get_key_info_cached_none_returns_none_without_keyring is internally inconsistent: the name says "without_keyring", but the assertions expect a keyring read to occur (call_count == 1) and the docstring says it should fall back to reading the keyring. Rename the test (and/or update its docstring) so it reflects the behavior being pinned.

[Copilot]

The PR description focuses on reverting two broken autofix commits to restore green CI, but this diff also includes a broad rewrite of the README (tagline, quick start, command reference, removed badges, etc.). Please confirm this README rewrite is intentional and in-scope for this PR; otherwise consider moving it to a separate PR so the revert/CI-fix intent stays focused.

[Copilot]

get_key_info’s docstring describes different behavior for "when omitted" vs "pass fingerprint=None", but with the current fingerprint: Optional[str] = None signature those cases are indistinguishable. Consider either (a) updating the docstring to say "when not provided or None" or (b) using a sentinel default if you truly need to distinguish an explicit None from omission.

[Copilot]

setup_command’s comment and tests frame this as "read key state exactly once per invocation", but the no-key path still calls generate_agent_key(), which itself calls get_key_fingerprint() internally (see signing.generate_agent_key). That means the command can still perform multiple keyring reads and can print "GPG key generated" even when the second read finds an existing key and no generation occurred. Consider threading the cached fingerprint through (e.g., adding an optional cached-fingerprint parameter to generate_agent_key) or adjusting the messaging/comment to match the actual behavior.

[Copilot]

rotate_command reads old_fingerprint = get_key_fingerprint() up front, but then calls delete_agent_key() and generate_agent_key(), both of which call get_key_fingerprint() internally in signing.py. If the intent is to avoid multiple keyring reads (and avoid inconsistencies under transient keyring failures), consider letting delete_agent_key / generate_agent_key accept the cached fingerprint or introducing variants that operate on a provided fingerprint.