feat: add security guardrails to prevent credential exposure

[ryderstorm]

Summary

Adds security guardrails throughout the SDD workflow to prevent API keys and sensitive data from being committed in proof artifacts.

Changes

• Added Security Considerations section to spec template
• Added security warnings to proof artifact creation workflow
• Added security validation gate to spec implementation validation
• Documented pre-commit hook options for secret scanning (gitleaks, truffleHog, detect-secrets)
• Added security best practices section to README

Closes #28

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Enhanced security guidance for handling credentials and sensitive data using placeholder values instead of real secrets
• Added secret scanning pre-commit hook options to detect and prevent secrets from being committed to the repository
• Introduced security validation gates throughout the workflow to ensure proof artifacts don't contain any exposed credentials or sensitive information

[coderabbitai]

Walkthrough

This PR introduces comprehensive security guidance across documentation and prompt templates to prevent accidental commit of API keys and credentials in proof artifacts. Changes include pre-commit hook setup instructions, explicit security warnings in workflow prompts, and a new validation gate to detect sensitive data.

Changes

Cohort / File(s)	Summary
Getting Started & Contribution Guides CONTRIBUTING.md, README.md	Added "Secret Scanning Pre-commit Hooks" section with setup instructions for gitleaks, truffleHog, and detect-secrets; introduced "Security Best Practices" section covering credential safeguards, placeholders, and sanitization for proof artifacts.
SDD Workflow Prompt Templates prompts/generate-spec.md, prompts/generate-task-list-from-spec.md, prompts/manage-tasks.md	Inserted explicit security notes and warnings in multiple workflow stages emphasizing that proof artifacts will be committed and must use placeholder values for API keys, tokens, and credentials; added security verification checklist items.
Validation & Quality Gates prompts/validate-spec-implementation.md	Added a new security-focused validation gate (GATE F) to detect and flag real API keys, tokens, passwords, or credentials in proof artifacts across evaluation rubrics, checks, and red flags.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Changes are primarily documentation and prompt template updates with consistent, repetitive security guidance patterns across files
• No code logic, logic density, or control-flow modifications
• Straightforward content additions focused on security messaging and warnings
• Risk is low as changes are additive and non-disruptive to existing workflows

Possibly related PRs

• refactor(workflow): comprehensive spec-driven workflow prompt refactoring #26 — Refactored the same prompt and documentation files (generate-spec.md, generate-task-list-from-spec.md, manage-tasks.md, validate-spec-implementation.md) that now receive these security-focused enhancements.

Suggested reviewers

• RobertKelly

Poem

🐰 Hop along the path secure,
With placeholders pure, our proof endure,
No API keys in the proof we keep,
Just [REDACTED] secrets—locked up deep!
gitleaks guards our repository clean,
The safest SDD workflow ever seen! 🔐

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding security measures to prevent credential exposure in the workflow.
Description check	✅ Passed	The description covers the key changes and closes the linked issue, though it doesn't complete the optional checklist items or provide additional implementation notes.
Linked Issues check	✅ Passed	The PR implements all primary objectives from issue #28: workflow prompt updates with security guidance [CONTRIBUTING.md, prompts files], pre-commit hook documentation [CONTRIBUTING.md], runtime safeguards through validation gates [validate-spec-implementation.md], and documentation warnings [README.md, multiple prompts].
Out of Scope Changes check	✅ Passed	All changes directly address issue #28 objectives: security guidance in prompts, pre-commit documentation, validation gates, and README warnings. No unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/issue-28-20251112-1700

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ryderstorm]

@claude fix the markdown issues that failed CI

[claude]

Claude finished @ryderstorm's task —— View job

---

Fixing Markdown Issues

Tasks

• Check CI status to identify markdown failures
• Review the specific markdown errors
• Fix markdown issues in affected files
• Commit and push changes

Changes Made

Fixed markdownlint errors in CONTRIBUTING.md by converting bold text headers to proper markdown headings:

• Line 36: **Option 1: gitleaks (recommended)** → #### Option 1: gitleaks (recommended)
• Line 46: **Option 2: truffleHog** → #### Option 2: truffleHog
• Line 57: **Option 3: detect-secrets** → #### Option 3: detect-secrets

Each heading now has a blank line after it as required by markdownlint rule MD036.

Summary

The markdown linting issues have been resolved. The CI checks should now pass when re-run. The changes have been committed and pushed to the PR branch claude/issue-28-20251112-1700.

---

Job Run | Branch

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

prompts/validate-spec-implementation.md (1)

77-78: Minor: Rephrase to avoid repetitive sentence structure.

The static analysis tool flagged that three successive sentences start the same way. While this is a style preference rather than a blocker, consider rewording GATE E or the section intro to improve readability.

- **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**.
- **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**.
- **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**.
+ **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**.
+ **GATE E:** Code follows identified repository standards and patterns → **REQUIRED**.
+ **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b8875bf and 4e61e88.

📒 Files selected for processing (6)

• CONTRIBUTING.md (1 hunks)
• README.md (1 hunks)
• prompts/generate-spec.md (1 hunks)
• prompts/generate-task-list-from-spec.md (1 hunks)
• prompts/manage-tasks.md (2 hunks)
• prompts/validate-spec-implementation.md (3 hunks)

🧰 Additional context used

🪛 LanguageTool

prompts/validate-spec-implementation.md

[style] ~78-~78: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ndards and patterns → REQUIRED. - GATE F (security): Proof artifacts contain...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (8)

CONTRIBUTING.md (1)

32-73: Well-structured pre-commit hooks guidance.

The Secret Scanning Pre-commit Hooks section provides clear, actionable options with concrete configuration examples. The placement after Development Setup and before Common Commands is appropriate.

prompts/generate-spec.md (1)

220-227: Security Considerations section well-integrated into spec template.

The new section fits naturally into the spec structure and prompts implementers to think about security requirements early in the planning phase. The guidance aligns with PR objectives around API key exposure prevention and proof artifact security.

prompts/generate-task-list-from-spec.md (1)

86-86: Security Note placement is strategic and effective.

Positioning the security warning at the planning stage (before task execution) gives developers clear guidance early when they're defining proof artifacts. The reminder that artifacts will be committed to the repository provides important context for the placeholder requirement.

prompts/validate-spec-implementation.md (2)

142-142: Security Check within Detailed Checks is comprehensive.

The security check at line 142 ("Proof artifacts contain no real API keys, tokens, passwords, or sensitive data") provides a concrete verification step that reinforces GATE F. Placement in the Detailed Checks section ensures this gets validated during the evidence verification phase.

---

169-169: Auto-CRITICAL severity for credentials is appropriate.

The Red Flags section correctly classifies real API keys, tokens, passwords, or credentials in proof artifacts as auto-CRITICAL. This severity level aligns with the security objectives and helps catch the most serious issues.

prompts/manage-tasks.md (2)

202-209: Comprehensive Security Warning with clear examples.

The security warning explicitly reminds developers that proof artifacts will be committed to the repository and provides concrete placeholder examples ([YOUR_API_KEY_HERE], [REDACTED]). The guidance on sanitizing outputs and reviewing before commit aligns well with the PR objectives and makes the security requirement actionable.

---

229-234: Security Check integrated into proof artifact verification workflow.

Including the Security Check in the proof artifact creation checklist and the SECURITY VERIFICATION item ensures developers actively verify the absence of credentials before committing. This represents a critical workflow integration point that supports the goal of preventing accidental credential exposure.

README.md (1)

201-212: README security section is appropriate; the tool references across documents serve different purposes.

The README correctly lists three valid pre-commit secret scanning tools including talisman, which is actively maintained and remains a legitimate 2025 option. CONTRIBUTING.md separately documents gitleaks (recommended), truffleHog, and detect-secrets as contributor setup options. This is not an inconsistency requiring correction—README provides general best-practice guidance while CONTRIBUTING.md specifies project-specific contributor setup. Both talisman and detect-secrets are valid, maintained tools suitable for their respective contexts.

[RobertKelly]

Maintaining the references and/or versions of these tools might be a challenge. Not against it but do we have any other references to 3rd party tools in the workflow?

[ryderstorm]

I don't think so, no. And pre-commit has an autoupdate command for automatically updating versions for hooks.

@claude answer RoberKelly's question, then make a small improvement to the changes in this PR to include a note about how users should check hook versions and use pre-commit autoupdate regularly.