Secret Scan

Core Question

Does the current diff, staged set, or repository context contain secret-like material that must not be exposed, committed, or pushed?

When To Use

Use this skill when:

• staged, unstaged, untracked, release, changelog, or tag content may contain credentials
• preflight detects sensitive-looking files or values
• a confidential file may have been committed
• the user asks whether secrets are present
• a secret may already have been committed or pushed

When Not To Use

Do not use this skill when:

• general large-file checks
• normal .gitignore hygiene without secret indicators
• rotating credentials or changing external systems
• rewriting history directly

Route to:

• large/binary file checks route to large-file-lfs
• secret already committed or pushed routes to undo-recover plus manual credential rotation
• commit blocking routes to atomic-commits after cleanup
• ignore-rule changes are out of scope; provide manual guidance or route to a future ignore-hygiene skill only if the repository later adds one

Required Evidence

Before action, inspect or establish:

• staged and unstaged diff with redaction
• untracked file names and high-risk path names
• secret-like pattern class, file, and line context
• whether content is staged, unstaged, committed, or pushed
• whether the user asked to remove content from Git only or also delete the local file
• remote/shared exposure evidence if available

No-evidence rule:

• Do not make strong claims without observed evidence.
• State assumptions when proceeding under incomplete evidence.
• Stop when missing evidence affects safety, correctness, user work, remote state, or irreversible action.

Operating Contract

You MAY:

• inspect relevant repository state and project files.
• generate a plan, report, or local artifact within the declared risk scope.
• route to another skill when the requested action is outside this skill's owner boundary.

You MUST:

• inspect before acting.
• keep the task within the declared owner boundary.
• classify state and risk before any meaningful action.
• preserve unrelated user work.
• verify outcomes proportional to risk.
• report evidence, assumptions, actions, verification, and residual risk.

You MUST NOT:

• invent project policy.
• expose secrets or sensitive values.
• mutate unrelated files or refs.
• perform destructive, remote, shared, history-rewriting, or irreversible actions without explicit action-specific confirmation.
• continue after unexpected destructive output.

State / Risk Table

Workflow

1. Identify the user goal and current owner boundary.
2. Inspect required evidence.
3. Classify repository/task state.
4. Classify risk using the declared scope.
5. Choose the minimal sufficient action or route.
6. Execute only allowed actions, if any.
7. Verify outcome or self-check the artifact.
8. Report result, evidence, verification, assumptions, and residual risk.

Decision Rules

• Never print or quote detected secret values.
• Report file path, line context, and secret type only with redaction.
• Block commit/push when secret-like values are staged.
• Treat "remove from Git history" as distinct from "delete the working-tree file."
• Do not claim revocation or remote removal without external evidence.

Workflow Guardrails

Repo-Excluded File Boundary

Trigger:

• The user asks to stop tracking, stop committing, ignore, or keep a local-only file out of Git without saying it is secret, confidential, credential-like, or exposed.

Default: <!-- guardrail:secret-scan.repo-excluded-not-secret -->

• Do not classify the file as secret by default; route Git index cleanup to undo-recover and preserve the working-tree file.

Must: <!-- guardrail:secret-scan.route-repo-excluded-cleanup -->

• Keep the response at path-level evidence unless secret-like content is explicitly in scope.
• Recommend index-only removal plus ignore/exclude handling, not secret purge.

Must not: <!-- guardrail:secret-scan.no-secret-purge-for-repo-excluded -->

• Read, print, quote, or infer sensitive contents from a repo-exclusion request alone.
• Run or route recovery metadata purge, reflog expiration, object pruning, garbage collection, or force-push cleanup unless the user separately classifies the content as sensitive exposure.

Verification:

• Confirm the routed plan preserves the local file and separates project-wide .gitignore from local-only .git/info/exclude.

Confidential File in History

Trigger:

• A confidential document, credential file, token, key, or password may have entered a commit.

Default:

• Classify exposure with redacted path-level evidence, then route Git mutation to undo-recover.

<!-- guardrail:secret-scan.preserve-working-tree -->

• Preserve a working-tree copy by default if the user asked to remove history, not delete the file.

Must: <!-- guardrail:secret-scan.route-history-rewrite -->

• Route Git history rewrite execution to undo-recover.
• Report whether remote exposure is known, unknown, or absent from inspected evidence.
• Warn that Git history cleanup does not replace revocation or rotation when the content is a credential.

Must not:

• Read, print, quote, or transmit confidential contents.
• Create rescue branches, patches, backup commits, or durable refs that preserve the confidential blob in Git.
• Delete the working-tree file by default.

<!-- guardrail:secret-scan.no-local-recovery-cleanup -->

• Run local recovery cleanup such as reflog expiration, object pruning, or garbage collection as part of exposure classification.

Requires explicit confirmation:

• Any history rewrite, local deletion, remote rewrite, or recovery metadata purge routed to undo-recover.

Verification:

• Confirm the routed plan preserves or deletes the working-tree copy according to explicit user intent.
• State that remote cleanup, external copies, and credential revocation require separate evidence.

Tool Rules

• May inspect diffs and file names locally.
• Must redact output.
• Must not transmit secrets to external systems.
• Must not rewrite history; route recovery.

Verification

Minimum verification:

• Verify post-cleanup diff no longer contains detected pattern.
• State scan scope and blind spots.
• For pushed secrets, report that credential rotation requires external confirmation.

Risk-based floor:

• R0-R1: evidence inspected and output self-checked.
• R2: inspect resulting diff or local state.
• R3: verify local state and report recovery limits.
• R4-R5: require explicit confirmation, preflight evidence, and post-action verification where this skill owns the action.

Output Contract

Final response must include:

## Result

- Decision, action, or artifact produced.

## Evidence

- Files, commands, diffs, refs, or assumptions used.

## Verification

- Checks performed and their result.

## Risks / Limitations

- Remaining uncertainty, blocked actions, or routed next steps.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Require explicit action-specific confirmation for:

• destructive local mutation.
• remote/shared mutation.
• history rewriting.
• security/secret/data impact.
• irreversible or hard-to-recover operation.

Broad approval such as "do whatever" is not enough for R4-R5 actions.

Lazy-load References

Load references/secret-patterns.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/redaction.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/recovery.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.