feat: add security guardrails to prevent credential exposure

.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)