feat: add security guardrails to prevent credential exposure

CONTRIBUTING.md

@@ -29,6 +29,49 @@ pre-commit install
 - Install pre-commit hooks once with `pre-commit install`.
 - Keep changes small and focused; prefer incremental PRs.
 
+### 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
+    hooks:
+      - id: gitleaks
+```
+
+#### Option 2: truffleHog
+
+```yaml
+# Add to .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/trufflesecurity/trufflehog
+    rev: v3.63.0
+    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
+    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.
+
 ### Common Commands
 
 ```bash

README.md

@@ -198,6 +198,19 @@ Run the prompts as an MCP server for programmatic access. This option is most us
 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

prompts/generate-spec.md

@@ -217,6 +217,15 @@ If no specific standards are identified, state "Follow established repository pa
 
 [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

@@ -83,6 +83,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

@@ -199,6 +199,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
@@ -217,10 +226,12 @@ For each parent task completion:
    - ## Demo Validation section showing criteria met
 [ ] **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
 **DEMO VERIFICATION**: Ensure file demonstrates all demo criteria are met
+**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

@@ -75,6 +75,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)
 
@@ -138,6 +139,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 Implementation**
    - Functional requirements are present in changed code
@@ -164,6 +166,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)