feat: add security guardrails to prevent credential exposure (#29)

* feat: add security guardrails to prevent credential exposure in proof artifacts

Add security warnings and best practices throughout SDD workflow to prevent
API keys and sensitive data from being committed in proof artifacts.

Changes:
- Add Security Considerations section to spec template
- Add security warnings to proof artifact creation workflow
- Add security validation gate to spec implementation validation
- Document pre-commit hook options for secret scanning
- Add security best practices section to README

Related to issue #28

Co-authored-by: Damien Storm <ryderstorm@users.noreply.github.com>

* fix: convert bold text to proper markdown headings in CONTRIBUTING.md

Fixes markdownlint errors MD036/no-emphasis-as-heading by converting
bold text used as headings to proper markdown heading syntax (####).

Co-authored-by: Damien Storm <ryderstorm@users.noreply.github.com>

* fix: clarify developer responsibility

Clarify responsibility for reviewing artifacts before pushing to remotes.

* build(release): configure semantic release commit message

Add explicit commit message template for release commits that includes
[skip ci] flag to prevent CI from triggering on automated version bumps.
Update configuration comments to reflect template repo nature and add
reference to python-semantic-release documentation.

* docs: add autoupdate reminder for pre-commit hook versions

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: ryderstorm

.releaserc.toml

@@ -1,13 +1,17 @@
+# See https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html
+# for detailed documentation on the configuration options.
+
 [semantic_release]
 # Use annotated tags like v1.2.3
 tag_format = "v{version}"
 # Allow 0.x.x versions (required for pre-1.0.0 releases)
 allow_zero_version = true
-# Don't update version in any files since this is a markdown-only repo
-# Version is tracked via git tags only
+# Don't update version in any files since this is a template repo
 version_variables = []
-# Generate changelog and commit version bumps
+# Assets to include in the release commit
 assets = []
+# Commit message for release commits - includes [skip ci] to prevent CI from running
+commit_message = "chore(release): {version} [skip ci]\n\nAutomatically generated by python-semantic-release"
 
 [semantic_release.changelog]
 # Generate CHANGELOG.md in Markdown

CONTRIBUTING.md

@@ -29,6 +29,51 @@ pre-commit install
 - Keep changes small and focused; prefer incremental PRs.
 - All prompts are plain Markdown files in the `prompts/` directory.
 
+### Recommended: Secret Scanning Pre-commit Hooks
+
+To prevent accidental commits of API keys, tokens, or other sensitive data (especially in proof artifacts), consider adding secret scanning to your pre-commit configuration:
+
+#### Option 1: gitleaks (recommended)
+
+```yaml
+# Add to .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0 # Update to the latest version (run `pre-commit autoupdate`)
+    hooks:
+      - id: gitleaks
+```
+
+#### Option 2: truffleHog
+
+```yaml
+# Add to .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/trufflesecurity/trufflehog
+    rev: v3.63.0 # Update to the latest version (run `pre-commit autoupdate`)
+    hooks:
+      - id: trufflehog
+        args: ['--trace', 'filesystem', '.']
+```
+
+#### Option 3: detect-secrets
+
+```yaml
+# Add to .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0 # Update to the latest version (run `pre-commit autoupdate`)
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+```
+
+After adding a secret scanner, run `pre-commit install` again to activate it. The scanner will automatically check files before each commit and block commits containing potential secrets.
+
+See the [pre-commit hooks documentation](https://pre-commit.com/hooks.html) for more secret scanning options.
+
+> ⚠️ **Note:** To keep your hooks current with the latest versions, periodically run `pre-commit autoupdate`.
+
 ### Common Commands
 
 ```bash

README.md

@@ -232,7 +232,32 @@ Once installed, you can use:
 - `/manage-tasks` - Manage task execution
 - `/validate-spec-implementation` - Validate implementation against spec
 
-## Installation
+### Option 3: MCP Server (Advanced)
+
+Run the prompts as an MCP server for programmatic access. This option is most useful for custom integrations and tools that support MCP.
+
+> Note: MCP prompt support is not uniformly supported across AI tools. See [docs/mcp-prompt-support.md](./docs/mcp-prompt-support.md) for details.
+
+### Workflow Essentials
+
+1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`.
+2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog.
+3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date.
+
+## Security Best Practices
+
+### Protecting Sensitive Data in Proof Artifacts
+
+Proof artifacts are committed to your repository and may be publicly visible. **Never commit real credentials or sensitive data.** Follow these guidelines:
+
+- **Replace credentials with placeholders**: Use `[YOUR_API_KEY_HERE]`, `[REDACTED]`, or `example-key-123` instead of real API keys, tokens, or passwords
+- **Use example values**: When demonstrating configuration, use dummy or example data instead of production values
+- **Sanitize command output**: Review CLI output and logs for accidentally captured credentials before committing
+- **Consider pre-commit hooks**: Tools like [gitleaks](https://github.com/gitleaks/gitleaks), [truffleHog](https://github.com/trufflesecurity/truffleHog), or [talisman](https://github.com/thoughtworks/talisman) can automatically scan for secrets before commits
+
+The SDD workflow prompts include built-in reminders about security, but ultimate responsibility lies with the developer to review artifacts before committing or pushing to remotes.
+
+### Installation
 
 ```bash
 # Clone the repository

prompts/generate-spec.md

@@ -290,6 +290,15 @@ Generate a comprehensive specification using this exact structure:
 
 [Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."]
 
+## Security Considerations
+
+[Identify security requirements and sensitive data handling needs. Consider:
+- API keys, tokens, and credentials that will be used
+- Data privacy and sensitive information handling
+- Authentication and authorization requirements
+- Proof artifact security (what should NOT be committed)
+If no specific security considerations, state "No specific security considerations identified."]
+
 ## Success Metrics
 
 [How will success be measured? Include specific metrics where possible.]

prompts/generate-task-list-from-spec.md

@@ -82,6 +82,8 @@ Proof artifacts provide evidence of task completion and are essential for the up
 - **Enable validation** (provide evidence for `/validate-spec-implementation`)
 - **Support troubleshooting** (logs, error messages, configuration states)
 
+**Security Note**: When planning proof artifacts, remember that they will be committed to the repository. Artifacts should use placeholder values for API keys, tokens, and other sensitive data rather than real credentials.
+
 ## Chain-of-Thought Analysis Process
 
 Before generating any tasks, you must follow this reasoning process:

prompts/manage-tasks.md

@@ -198,6 +198,15 @@ Each parent task must include artifacts that:
 - **Enable validation** (provide evidence for `/validate-spec-implementation`)
 - **Support troubleshooting** (logs, error messages, configuration states)
 
+### Security Warning
+
+**CRITICAL**: Proof artifacts will be committed to the repository. Never include sensitive data:
+
+- Replace API keys, tokens, and secrets with placeholders like `[YOUR_API_KEY_HERE]` or `[REDACTED]`
+- Sanitize configuration examples to remove credentials
+- Use example or dummy values instead of real production data
+- Review all proof artifact files before committing to ensure no sensitive information is present
+
 ### Proof Artifact Creation Protocol
 
 ```markdown
@@ -216,10 +225,12 @@ For each parent task completion:
    - ## Verification section showing proof artifacts demonstrate required functionality
 [ ] **Format with Markdown**: Use code blocks, headers, and clear organization
 [ ] **Verify File Content**: Ensure the markdown file contains all required evidence
+[ ] **Security Check**: Scan proof file for API keys, tokens, passwords, or other sensitive data and replace with placeholders
 
 **SIMPLE VERIFICATION**: One file per task, all evidence included
 **CONTENT VERIFICATION**: Check the markdown file contains required sections
 **VERIFICATION**: Ensure proof artifact file demonstrates all required functionality
+**SECURITY VERIFICATION**: Confirm no real credentials or sensitive data are present
 
 **The single markdown proof file must be created BEFORE the parent task commit**
 ```

prompts/validate-spec-implementation.md

@@ -74,6 +74,7 @@ If no spec is provided, follow this exact sequence:
 - **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**.
 - **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**.
 
 ## Evaluation Rubric (score each 0–3 to guide severity)
 
@@ -137,6 +138,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard:
    - CLI commands execute successfully with expected output
    - Test references exist and can be executed
    - Screenshots/demos show required functionality
+   - **Security Check**: Proof artifacts contain no real API keys, tokens, passwords, or sensitive data
 
 3) **Requirement Coverage**
    - Proof Artifacts exist for each Functional Requirement
@@ -163,6 +165,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard:
 - Any `Unknown` entries in the Coverage Matrix
 - Repository pattern violations (coding standards, quality gates, workflows)
 - Implementation that ignores identified repository conventions
+- **Real API keys, tokens, passwords, or credentials in proof artifacts** (auto CRITICAL)
 
 ## Output (single human-readable Markdown report)