Secret Handling

Patterns

Prohibited File Reads

NEVER read these files:

• .env (production secrets)
• .env.local (local dev secrets)
• .env.production (production environment)
• .env.development (development environment)
• .env.staging (staging environment)
• .env.test (test environment with real credentials)
• Any file matching .env.* UNLESS explicitly allowed (see below)

Allowed alternatives:

• .env.example (safe — contains placeholder values, no real secrets)
• .env.sample (safe — documentation template)
• .env.template (safe — schema/structure reference)

If you need config info:

1. Ask the user directly — “What’s the database connection string?”
2. Read .env.example — shows structure without exposing secrets
3. Read documentation — check README.md, docs/, config guides

NEVER assume you can “just peek at .env to understand the schema.” Use .env.example or ask.

Prohibited Output Patterns

NEVER write these to .squad/ files:

What to write instead:

• Placeholder values: DATABASE_URL=<set in .env>
• Redacted references: API key configured (see .env.example)
• Architecture notes: “App uses JWT auth — token stored in session”
• Schema documentation: “Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)”

Scribe Pre-Commit Validation

Before committing .squad/ changes, Scribe MUST:

1. Scan all staged files for secret patterns (use regex table above)

2. Check for prohibited file names (don’t commit .env even if manually staged)

3. If secrets detected:

   • STOP the commit (do NOT proceed)
   • Remove the file from staging: git reset HEAD <file>
   • Report to user:

     Copy

     🚨 SECRET DETECTED — commit blocked
     
     File: .squad/decisions/inbox/river-db-config.md
     Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod
     
     This file contains credentials and MUST NOT be committed.
     Please remove the secret, replace with placeholder, and try again.

   • Exit with error (never silently skip)

4. If no secrets detected:

   • Proceed with commit as normal

Implementation note for Scribe:

• Run validation AFTER staging files, BEFORE calling git commit
• Use PowerShell Select-String or git diff --cached to scan staged content
• Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior

Remediation — If a Secret Was Already Committed

If you discover a secret in git history:

1. STOP immediately — do not make more commits
2. Alert the user:

   Copy

   🚨 CREDENTIAL LEAK DETECTED
   
   A secret was found in git history:
   Commit: abc1234
   File: .squad/decisions/inbox/agent-config.md
   Pattern: API_KEY=sk-proj-...
   
   This requires immediate remediation:
   1. Revoke the exposed credential (regenerate API key, rotate password)
   2. Remove from git history (git filter-repo or BFG)
   3. Force-push the cleaned history
   
   Do NOT proceed with new work until this is resolved.

3. Do NOT attempt to fix it yourself — secret removal requires specialized tools
4. Wait for user confirmation before resuming work

Examples

✓ Correct: Reading Config Schema

Agent needs to know what environment variables are required:

✗ Incorrect: Reading Live Credentials

Agent needs to know database schema:

Correct approach:

✓ Correct: Scribe Pre-Commit Validation

Scribe is about to commit:

Anti-Patterns

• ❌ Reading .env “just to check the schema” — use .env.example instead
• ❌ Writing “sanitized” connection strings that still contain credentials
• ❌ Assuming “it’s just a dev environment” makes secrets safe to commit
• ❌ Committing first, scanning later — validation MUST happen before commit
• ❌ Silently skipping secret detection — fail loud, never silent
• ❌ Trusting agents to “know better” — enforce at multiple layers (prompt, hook, architecture)
• ❌ Writing secrets to “temporary” files in .squad/ — Scribe commits ALL .squad/ changes
• ❌ Extracting “just the host” from a connection string — still leaks infrastructure topology