Privacy gate

Privacy Gate

Use this skill when repository content needs a privacy and secret check before commit, push, packaging, installation, or sharing.

Core Rule

Call the bundled CLI. Do not reimplement detection logic in chat or in a client-specific adapter. <package-root> below means the directory containing this SKILL.md (for example the installed skill path or a vendored privacy-gate/).

python3 "<package-root>/scripts/privacy_gate.py" scan --staged
python3 "<package-root>/scripts/privacy_gate.py" scan --path .
python3 "<package-root>/scripts/privacy_gate.py" sanitize --path FILE --write
python3 "<package-root>/scripts/privacy_gate.py" install-hook

The install-hook command writes a .githooks/pre-commit that resolves the scanner at run time (a vendored copy, an installed absolute path, or the PRIVACY_GATE_SCRIPT override), so it keeps working from any repository, not only one that vendors privacy-gate/. Pass install-hook --force to replace a foreign pre-commit hook or reassign an existing core.hooksPath. Pass install-hook --portable for a shared repo so the committed hook carries no machine-specific path; pair it with a vendored privacy-gate/ or the PRIVACY_GATE_SCRIPT override.

Bundled files: scripts/privacy_gate.py (scanner, source of truth), scripts/test_privacy_gate.py (regression tests), references/policy.md (policy).

Flags And Exit Codes

• Default scan exits nonzero only on BLOCK findings (high-confidence secrets); WARN findings (PII) print but do not fail. This is the pre-commit default.
• --fail-on-warn (or its alias --strict) also fails on WARN findings; use it for stricter CI gates and release checks.
• --json emits a structured report instead of text.

Allowlist reviewed false positives without disabling the gate. Two inline markers, both leaving a visible in-diff audit trail: privacy-gate: allow in a comment suppresses PII warnings on that line, but a high-confidence secret still blocks; privacy-gate: allow-secret is required to suppress a secret on that line and relies entirely on diff review. Or list glob patterns in a committed .privacygateignore to skip paths. Neither affects file-level blocks (binary, .env). See references/policy.md.

Workflow

1. Run scan --staged before committing staged changes; add --strict in CI to also fail on PII warnings.
2. Run scan --path . before publishing, packaging, or syncing a repo copy.
3. Treat BLOCK findings as release blockers.
4. Treat WARN findings as review items that may need redaction or manual confirmation.
5. Use sanitize --path FILE --write only for text-file PII cleanup; review the printed preview first.
6. Remove and rotate credentials instead of sanitizing them.

Policy Reference

Read references/policy.md before changing detection rules, hook behavior, or sanitizer behavior. The policy distinguishes high-confidence secrets that block release from privacy-like content that should be reviewed.

Maintainer Checks

After changing this skill (not needed for normal use), run the regression tests plus the repo gatekeeper:

python3 "<package-root>/scripts/test_privacy_gate.py"
python3 -S skill-forge/scripts/inspect_skill_package.py "<package-root>" --json --strict
claude plugin validate --strict "<package-root>"  # when Claude tooling is available