AI Assistant Secret Handling Rules

## Purpose

Use these rules when an AI coding assistant can see, edit, summarize, test, or
publish code that might contain secrets. Secrets include API keys, passwords,
private keys, SSH keys, tokens, cookies, session identifiers, webhook secrets,
database URLs, cloud credentials, signing keys, and sensitive internal
identifiers.

The safest assistant behavior is boring and explicit: do not reveal the value,
do not preserve it in generated output, do not move it into another public
place, and do not treat cleanup as enough when a real credential was exposed.

## Secret Classification

Classify a value as secret or potentially secret when it is:

- a credential value, private key, token, password, cookie, webhook secret, or
  connection string;
- a live-looking value in `.env`, config, CI, deployment, container, cloud, or
  package-publish settings;
- a generated fixture, screenshot, log, trace, notebook output, prompt, or
  documentation sample that resembles a credential;
- an internal hostname, account ID, customer identifier, database name, or
  incident detail that should not be public;
- a value the assistant cannot prove is synthetic.

When uncertain, handle the value as sensitive and ask for a safe placeholder.

## Assistant Rules

- Never paste real secret values into prompts, model output, PR descriptions,
  issue comments, commit messages, generated docs, test fixtures, or examples.
- Replace discovered values with stable placeholders such as
  `EXAMPLE_API_KEY`, `REDACTED_DATABASE_URL`, or `YOUR_SERVICE_TOKEN`.
- Name the required variable or secret store key, but not the value.
- Preserve local-only files in `.gitignore` when the project expects secrets in
  untracked environment files.
- Prefer CI secret stores, deployment secret stores, or credential helpers over
  hardcoded config.
- Do not transform a secret into another leak, such as a base64 string, partial
  token, screenshot, log line, or generated summary.
- Stop and escalate when a real secret appears in history, public review text,
  CI logs, chat transcripts, or generated artifacts.

## Commit And PR Rules

Before committing assistant-generated work:

1. Check staged files, untracked generated files, snapshots, notebooks, reports,
   logs, and docs for real-looking secrets.
2. Verify `.gitignore` covers local credential files, but do not rely on
   `.gitignore` after a secret has already been committed.
3. Review CI workflow changes for accidental secret printing, broad environment
   export, unsafe debugging, or untrusted pull request exposure.
4. Keep the PR body privacy-safe: describe the secret name or storage mechanism
   without revealing values, account IDs, or private incident context.
5. If a secret was exposed, request rotation and history cleanup from the owner
   before presenting the PR as safe.

## Storage Rules

- Store local development values in local-only environment files or credential
  helpers according to the project policy.
- Store CI and deployment values in the platform's secret store, not in YAML,
  shell scripts, Dockerfiles, docs, or committed examples.
- Keep sample files synthetic and obvious: `example.env`, `.env.example`, and
  docs should contain placeholders, not copied local values.
- Scope secrets narrowly by environment, service, permission, and expiration
  where the platform supports it.
- Do not create new long-lived credentials to make an assistant task easier.

## Rotation And Cleanup Rules

Editing the file is not enough when a real secret was exposed.

- Mark the credential as exposed.
- Notify the owner or security channel.
- Rotate, revoke, or expire the secret according to the project's policy.
- Remove or rewrite public history only through the maintainer-approved path.
- Check secondary copies: CI logs, issue comments, PR bodies, screenshots,
  traces, notebooks, generated docs, package artifacts, and assistant
  transcripts.
- Add or update a scanner or review checklist so the same leak is less likely to
  recur.

## Review Checklist

- [ ] {"task": "No real values", "description": "Diffs, prompts, docs, tests, fixtures, logs, screenshots, and generated artifacts contain placeholders instead of real secrets"}
- [ ] {"task": "Storage named", "description": "The entry or PR names the expected environment variable, CI secret, vault key, or credential helper without revealing the value"}
- [ ] {"task": "Local files ignored", "description": "Local credential files are untracked or ignored according to project policy"}
- [ ] {"task": "CI is safe", "description": "Workflow changes do not print secrets, export them broadly, or expose them to untrusted pull requests"}
- [ ] {"task": "Exposure escalated", "description": "Real or suspected exposed secrets trigger owner notification, rotation, and cleanup review"}
- [ ] {"task": "Public notes redacted", "description": "PR and issue text avoid raw tokens, private IDs, customer details, and incident context"}

## Do Not Merge When

- a real-looking secret remains in the source diff, generated files, docs,
  examples, tests, screenshots, logs, or notebook output;
- a PR claims "secret removed" but does not mention rotation or owner review
  after exposure;
- a workflow prints environment variables, dumps contexts, or exposes secrets to
  untrusted code paths;
- a sample config uses a copied local value instead of a placeholder;
- the assistant included token fragments, hashes, screenshots, or summaries that
  still help identify the secret;
- cleanup requires private security handling but the public PR contains the
  sensitive evidence.

## Troubleshooting

- **A value might be fake:** treat it as sensitive until the owner confirms it is
  synthetic or expired.
- **The secret is already in history:** stop normal review and follow the
  repository's history-cleanup and rotation process.
- **The tests need credentials:** use test doubles, local-only environment
  variables, or CI secret stores; do not commit the value.
- **A scanner reports a false positive:** document why it is synthetic, then
  keep the example clearly fake.
- **The assistant needs context:** provide the secret name, permission scope,
  and storage location, not the value.

## Duplicate Check

Checked existing rules, guides, collections, hooks, agents, skills, commands,
open PRs, and closed PR history for secret-handling rules, credential safety,
secret scanning, environment variable review, pre-write secret checks, and AI
assistant privacy guidance.

Adjacent content includes secret-scanning hooks, environment-variable validation,
privacy metadata rules, and secure workflow guides. This entry is distinct
because it gives portable do/don't behavior for AI coding assistants deciding
how to handle secrets in prompts, diffs, generated artifacts, CI workflows, and
public review notes.

## References

- OWASP Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
- The Twelve-Factor App config guidance: https://12factor.net/config
- Git gitignore documentation: https://git-scm.com/docs/gitignore
- Git credential storage documentation: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
- GitHub Actions secrets documentation: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets
- GitHub sensitive-data removal documentation: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository