ace-git-secrets 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42f92fe3039656ea5e9d23913cbf2293c56f52926d6058c72c00f17de01aa75c
+  data.tar.gz: 898f5d444459ef601d59e5d3ec83fc06e17e90e2f995c4af567f98444d3d99b9
+SHA512:
+  metadata.gz: 0fe1d2d6b8f689c1f0a6e4239bed7a8978c6eccaf82d477a3cf97f147c02324b639d6731cf372755a1a4dbd5299cdb932647924b719ca214a3a2bf77d4b9a250
+  data.tar.gz: 8fdbb1ced752669af8931b294ca7d1b8b56cb1597cc0026fdae1b55055d2c35ef78646e289a9bca7c01a4bef80aed75bd399e78eacc4aadb293274e7932cebbb

data/.ace-defaults/git-secrets/config.yml

@@ -0,0 +1,63 @@
+# ace-git-secrets configuration
+# Place in .ace/git-secrets/config.yml to customize
+# ADR-022: This file is the single source of truth for defaults
+#
+# IMPORTANT: gitleaks is required for token detection
+# Install with: brew install gitleaks
+
+# Gitleaks configuration
+# ace-git-secrets uses gitleaks for all token detection.
+# The config is resolved via cascade:
+#   1. .ace/git-secrets/gitleaks.toml (user override)
+#   2. .ace-defaults/git-secrets/gitleaks.toml (gem default)
+# To customize gitleaks rules, copy the gem default to .ace/git-secrets/gitleaks.toml
+# and modify as needed. The file path is resolved automatically.
+# Note: This is NOT a config option - gitleaks.toml must be a separate file.
+
+# Default file exclusions (files that NEVER contain secrets)
+# Only excludes files that cannot contain real secrets
+# Test fixtures/cassettes are NOT excluded - use token-based whitelisting instead
+exclusions:
+  # Lock files (contain integrity hashes, not secrets)
+  - "**/package-lock.json"
+  - "**/yarn.lock"
+  - "**/pnpm-lock.yaml"
+  - "**/Gemfile.lock"
+  - "**/composer.lock"
+  - "**/Cargo.lock"
+  - "**/poetry.lock"
+  - "**/Pipfile.lock"
+  - "**/go.sum"
+  # Minified files (generated code)
+  - "**/*.min.js"
+  - "**/*.min.css"
+  # Build outputs (generated, not source)
+  - "**/dist/**"
+  - "**/build/**"
+  - "**/node_modules/**"
+  - "**/vendor/**"
+  - "**/.bundle/**"
+
+# Whitelist patterns (will not be flagged)
+# Use specific token values, not file paths (more secure)
+whitelist: []
+# whitelist:
+#   - pattern: 'ghp_example_for_docs'
+#     reason: Documentation example
+#   - pattern: 'sk_test_fake123'
+#     reason: Test fixture token
+
+# Output settings
+output:
+  format: table  # Verbose output format: table, json, yaml
+  mask_tokens: true  # Always mask token values in output
+  directory: .ace-local/git-secrets  # Directory for report files
+
+# GitHub Enterprise support (optional)
+# Uncomment and set your GitHub Enterprise API URL for token revocation
+# github:
+#   api_url: https://github.mycompany.com/api/v3
+
+# API request settings (optional)
+# Custom User-Agent header for API requests (useful for corporate environments)
+# user_agent: "my-company/1.0"

data/.ace-defaults/git-secrets/gitleaks.toml

@@ -0,0 +1,14 @@
+# Default gitleaks configuration for ace-git-secrets
+# ADR-022: This file provides default gitleaks rules
+# Place custom rules in .ace/git-secrets/gitleaks.toml to override
+
+# Extend gitleaks default rules
+[extend]
+useDefault = true
+
+# Add organization-wide custom rules here
+# Example:
+# [[rules]]
+# id = "internal-api-key"
+# description = "Internal API Key"
+# regex = '''INTERNAL_[A-Za-z0-9]{32}'''

data/.ace-defaults/nav/protocols/guide-sources/ace-git-secrets.yml

@@ -0,0 +1,10 @@
+---
+# Guide Sources Protocol Configuration for ace-git-secrets gem
+name: ace-git-secrets
+type: gem
+description: Guides from ace-git-secrets gem
+priority: 10
+config:
+  relative_path: handbook/guides
+  pattern: "*.g.md"
+  enabled: true

data/.ace-defaults/nav/protocols/wfi-sources/ace-git-secrets.yml

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-git-secrets gem
+# This enables workflow discovery from the installed ace-git-secrets gem
+
+name: ace-git-secrets
+type: gem
+description: Git secrets workflow instructions from ace-git-secrets gem
+priority: 10
+
+# Configuration for workflow discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/workflow-instructions)
+  relative_path: handbook/workflow-instructions
+
+  # Pattern for finding workflow files (default: *.wf.md)
+  pattern: "*.wf.md"
+
+  # Enable discovery
+  enabled: true

data/CHANGELOG.md

@@ -0,0 +1,298 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.13.0] - 2026-03-23
+
+### Added
+- Arch Linux install instructions for `gitleaks` and `git-filter-repo` in getting-started guide.
+
+### Changed
+- Aligned gemspec summary with README tagline.
+- Moved Installation from README to Getting Started guide as a proper section.
+- Clarified agent workflow references in Use Cases (removed raw `/as-` prefix).
+- Fixed broken relative links in `handbook/guides/security/rust.md` and `handbook/guides/security/typescript.md`.
+- Redesigned getting-started demo tape: sandbox with scan, history rewrite, and verify-clean flow.
+- Re-recorded getting-started demo GIF from new tape.
+
+## [0.12.2] - 2026-03-23
+
+### Changed
+- Refreshed package README layout with quick links, use-case flow, and standardized section ordering to match the current ACE package pattern.
+
+## [0.12.1] - 2026-03-22
+
+### Technical
+- Replaced HTML-sensitive placeholder paths in getting-started examples with a concrete saved-report example.
+
+## [0.12.0] - 2026-03-22
+
+### Changed
+- Reworked package documentation with a landing-page README, tutorial getting-started guide, refreshed usage reference, handbook catalog, demo assets, and aligned gem metadata messaging.
+
+### Fixed
+- Corrected remediation examples to reuse the saved JSON report path under `.ace-local/git-secrets/sessions/`.
+- Clarified that JSON reports are reusable for `revoke` and `rewrite-history`, while Markdown reports are for human-readable review.
+- Included `docs/**/*` in gem packaging so linked documentation ships with the gem.
+
+## [0.11.0] - 2026-03-18
+
+### Changed
+- Expanded `TS-SECRETS-001` E2E coverage with a new `check-release` gate test case and synchronized scenario runner/verifier manifests to 8-goal execution.
+
+### Technical
+- Added task-level E2E lifecycle artifacts (`e2e-review.md`, `e2e-change-plan.md`) documenting coverage analysis and rewrite decisions for `8qe.t.h5e.5`.
+
+## [0.10.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.10.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.9.3] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.9.2] - 2026-03-13
+
+### Changed
+- Updated canonical git security skills to explicitly run bundled workflows in the current project and execute them end-to-end.
+
+## [0.9.1] - 2026-03-12
+
+### Changed
+- Updated README remediation guidance to load the token-remediation workflow through `ace-bundle`.
+
+## [0.9.0] - 2026-03-10
+
+### Added
+- Added the canonical handbook-owned security audit skill for git secret scanning workflows.
+
+
+## [0.8.3] - 2026-03-04
+
+### Fixed
+- Usage docs and token-remediation workflow corrected to short-name path convention (`.ace-local/git-secrets/` not `.ace-local/ace-git-secrets/`)
+
+## [0.8.2] - 2026-03-04
+
+### Fixed
+- Reverted Gitleaks temporary workspace handling to Ruby temp primitives (`Tempfile`/`Dir.mktmpdir`) instead of project-local temporary workspaces.
+
+## [0.8.1] - 2026-03-04
+
+### Fixed
+- README and usage docs updated to short-name path convention (`.ace-local/git-secrets` not `.ace-local/ace-git-secrets`)
+
+## [0.8.0] - 2026-03-04
+
+### Changed
+- Default session/report directory migrated from `.cache/ace-git-secrets/sessions` to `.ace-local/git-secrets/sessions`
+- Gitleaks workspace now uses `Ace::Support::Items::Atoms::TmpWorkspace` for deterministic `.ace-local/tmp` paths
+
+## [0.7.11] - 2026-02-24
+
+### Technical
+- Correct TS-SECRETS-001 E2E runner config path references to `.ace/git-secrets/config.yml` and document whitelist file-rule setup for fixture exclusions.
+
+## [0.7.10] - 2026-02-23
+
+### Technical
+- Updated internal dependency version constraints to current releases
+
+## [0.7.9] - 2026-02-22
+
+### Changed
+- Migrate top-level CLI help to the standard multi-command help pattern with explicit `help`, `--help`, and `-h` commands.
+
+### Technical
+- Remove custom default-routing (`CLI.start`, `KNOWN_COMMANDS`, `DEFAULT_COMMAND`) from CLI registry.
+- Move config preloading and no-args help handling to `exe/ace-git-secrets` before dry-cli dispatch.
+- Update CLI command tests to assert executable-equivalent dry-cli dispatch behavior.
+
+## [0.7.7] - 2026-02-19
+
+### Technical
+- Namespace security workflow instructions into git/ subdirectory
+
+## [0.7.6] - 2026-02-11
+
+### Technical
+- Remove legacy MT-SECRETS-002 E2E test file (functionality covered by TS-SECRETS-002)
+
+## [0.7.5] - 2026-02-11
+
+### Added
+- E2E tests for scan, rewrite, and configuration workflows
+- Full workflow and config cascade E2E tests
+
+### Fixed
+- Ensure proper exit codes for scan, revoke, rewrite commands (CLI wrappers now
+  raise Error with correct exit_code instead of returning 0)
+- Move broken-report fixture out of .cache to avoid gitignore
+- Resolve non-zero exit code for --help flag
+
+### Changed
+- Migrate E2E tests to per-TC directory format
+
+## [0.7.4] - 2026-01-31
+
+### Fixed
+- Optimize slow tests by stubbing subprocess calls
+  - Convert clean_working_directory? tests from real git calls to stubbed Open3.capture2
+  - Remove flaky test_available_returns_true_when_git_filter_repo_installed
+  - Suite time improved from ~1.4s to ~1.1s (~23% faster)
+
+## [0.7.3] - 2026-01-31
+
+### Performance
+- Moved git integration tests to E2E test suite
+  - Tests now run via `/ace:run-e2e-test ace-git-secrets MT-SECRETS-001`
+  - Added HistoryScanner unit tests with mocked gitleaks
+  - Test execution time reduced from 4.5s to ~1.8s (60% reduction)
+
+## [0.7.2] - 2026-01-16
+
+### Changed
+- Rename context: to bundle: keys in configuration files
+
+## [0.7.1] - 2026-01-15
+
+### Changed
+- Migrate CLI commands to Hanami pattern
+  - Move commands from `commands/` to `cli/commands/`
+  - Update namespace from `Commands::*` to `CLI::Commands::*`
+  - Business logic command classes (`*Command`) remain in `commands/`
+
+## [0.7.0] - 2026-01-07
+
+### Changed
+- **BREAKING**: Migrated CLI framework from Thor to dry-cli (task 179.09)
+  - Replaced `thor` dependency with `dry-cli ~> 1.0`
+  - Created dry-cli command wrappers (Scan, Rewrite, Revoke, CheckRelease)
+  - Maintained complete command parity and user-facing behavior
+
+## [0.6.0] - 2026-01-07
+
+### Changed
+- **BREAKING**: Scan report filenames changed from 14-character timestamps to 6-character Base36 compact IDs
+  - Example: `20251129-143000-report.json` → `i50jj3-report.json`
+  - Reports now stored in `sessions/` subdirectory: `.cache/ace-git-secrets/sessions/`
+- Migrate to Base36 compact IDs for session and file naming (via ace-timestamp)
+
+### Added
+- Dependency on ace-timestamp for compact ID generation
+- Organized report storage with `sessions/` subdirectory
+
+## [0.5.0] - 2026-01-05
+
+### Added
+- Thor CLI migration with standardized command structure
+- ConfigSummary display for effective configuration with sensitive key filtering
+- Comprehensive CLI help documentation across all commands
+- --help support for all subcommands
+- exit_on_failure and version mapping standardization
+
+### Changed
+- Adopted Ace::Core::CLI::Base for standardized options (--quiet, --verbose, --debug)
+- Migrated from OptionParser to Thor framework
+- Added method_missing for default subcommand support
+
+## [0.4.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.3.1] - 2025-12-30
+
+### Changed
+
+- Replace ace-support-core dependency with ace-config for configuration cascade
+- Migrate from Ace::Core to Ace::Config.create() API
+- Migrate from `resolve_for` to `resolve_namespace` for cleaner config loading
+
+## [0.3.0] - 2025-12-30
+
+### Changed
+
+* Rename `.ace.example/` to `.ace-defaults/` for gem defaults directory
+
+
+## [0.2.0] - 2025-12-22
+
+### Added
+
+- Raw token persistence in scan results for remediation workflow
+- Thread-safe blob caching for improved performance
+- ADR-023 documenting security model decisions
+- Enhanced audit logging for compliance tracking
+- Configurable user-agent header for API client
+- Configurable binary file extensions via `binary_extensions` parameter
+- `--quiet` flag for CI-friendly minimal output
+
+### Changed
+
+- **BREAKING**: Gitleaks is now required for scanning (removed internal Ruby pattern detection fallback)
+- Simplified architecture by delegating all pattern matching to gitleaks
+- Use `Ace::Core::Atoms::DeepMerger` from ace-support-core instead of local deep_merge
+- Improved error messages for gitleaks validation and missing patterns files
+- Log batch fallback reason when git cat-file --batch fails
+
+### Removed
+
+- Internal Ruby pattern detection (TokenPatternMatcher) - now delegates entirely to gitleaks
+- GitBlobReader complex blob parsing - simplified to use gitleaks output
+- ThreadSafeBlobCache - no longer needed without internal pattern matching
+
+### Fixed
+
+- Repository path validation in GitRewriter to prevent operations on invalid paths
+
+## [0.1.0] - 2025-12-20
+
+### Added
+
+- Initial release of ace-git-secrets gem
+- `ace-git-secrets scan` - Scan Git history for authentication tokens
+  - Supports GitHub PATs (classic, OAuth, App, fine-grained)
+  - Supports LLM API keys (Anthropic, OpenAI)
+  - Supports AWS credentials (Access Key, Session Token)
+  - Uses gitleaks when available, falls back to Ruby patterns
+  - Output formats: table, JSON, YAML
+- `ace-git-secrets rewrite-history` - Remove tokens from Git history
+  - Uses git-filter-repo for safe history rewriting
+  - Dry-run mode for preview
+  - Automatic backup creation
+  - Confirmation required for destructive operations
+- `ace-git-secrets revoke` - Revoke tokens via provider APIs
+  - GitHub token revocation via Credential Revocation API
+  - Instructions for manual revocation (Anthropic, OpenAI, AWS)
+- `ace-git-secrets check-release` - Pre-release security gate
+  - CI-friendly exit codes (0=pass, 1=fail)
+  - Strict mode for medium confidence matches
+- Models: DetectedToken, RevocationResult, ScanReport
+- Atoms: TokenPatternMatcher, GitleaksRunner, GitBlobReader, ServiceApiClient
+- Molecules: HistoryScanner, GitRewriter, TokenRevoker
+- Organisms: SecurityAuditor, HistoryCleaner, ReleaseGate
+- Configuration via ace-core config cascade (.ace/git-secrets/config.yml)
+- ATOM architecture following ACE gem standards
+
+
+## [0.7.8] - 2026-02-22
+
+### Fixed
+- Standardized quiet, verbose, debug option descriptions to canonical strings

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+<div align="center">
+  <h1> ACE - Git Secrets </h1>
+
+  Scan, revoke, and remove leaked credentials from Git history before they cause damage.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-git-secrets"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-git-secrets.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+![ace-git-secrets demo](docs/demo/ace-git-secrets-getting-started.gif)
+
+`ace-git-secrets` gives developers and coding agents a focused remediation loop for leaked credentials: detect exposure with gitleaks-backed scanning, revoke impacted tokens by provider, and safely clean repository history with dry-run-first safeguards.
+
+## How It Works
+
+1. Scan commits with gitleaks-backed detection and capture a reusable saved report for remediation workflows.
+2. Revoke high-confidence findings from the saved scan report using provider-aware revocation flows.
+3. Preview history rewrites with `--dry-run`, execute cleanup when ready, then gate releases with `check-release`.
+
+## Use Cases
+
+**Detect leaked credentials in Git history** - run [`ace-git-secrets`](docs/usage.md) to scan commits and capture a reusable JSON report for remediation. Use the `as-git-security-audit` agent workflow for a guided audit.
+
+**Revoke exposed tokens by provider** - use the `as-git-token-remediation` workflow to revoke high-confidence findings from the saved scan report for GitHub PATs and other supported token classes before any history rewrites.
+
+**Clean history safely with dry-run-first safeguards** - preview rewrite changes with [`ace-git-secrets rewrite-history --dry-run`](docs/usage.md), execute cleanup when ready, then block release pipelines if secrets are still present.
+
+**Coordinate with git workflow tools** - pair with [ace-bundle](../ace-bundle) for loading remediation workflows, [ace-git](../ace-git) for repository context before cleanup, and [ace-git-commit](../ace-git-commit) for follow-up commits after remediation work.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+# ADR-021 compliant Rake::TestTask setup
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+# CI compatibility alias (ADR-021)
+task spec: :test
+
+# Default task
+task default: :test

data/docs/demo/ace-git-secrets-getting-started.tape.yml

@@ -0,0 +1,38 @@
+---
+description: Show ace-git-secrets detecting and removing a leaked token
+tags:
+- ace-git-secrets
+- docs
+- security
+settings:
+  font_size: 16
+  width: 960
+  height: 540
+  format: gif
+setup:
+- sandbox
+- git-init
+- run: printf 'GITHUB_TOKEN=ghp_123456789012345678901234567890123456\n' > .env && git add .env && git commit -qm "add config with token"
+scenes:
+- name: Scan for leaked credentials
+  commands:
+  - type: ace-git-secrets scan
+    sleep: 6s
+- name: Commit scan output before rewrite
+  commands:
+  - type: git add -A && git commit -qm 'save scan report'
+    sleep: 3s
+- name: Rewrite history to remove the token
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-git-secrets rewrite-history --force
+    sleep: 6s
+- name: Verify clean history
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-git-secrets scan
+    sleep: 6s
+teardown:
+- cleanup

data/docs/demo/fixtures/README.md

@@ -0,0 +1,3 @@
+# Demo fixtures for ace-git-secrets
+
+Seed data used by YAML demo setup.

data/docs/demo/fixtures/sample.txt

@@ -0,0 +1 @@
+sample fixture content

data/docs/getting-started.md

@@ -0,0 +1,109 @@
+---
+doc-type: user
+title: Getting Started with ace-git-secrets
+purpose: Tutorial for first-run ace-git-secrets workflows
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-git-secrets
+
+Use `ace-git-secrets` when you need to find leaked credentials, revoke them quickly, and remove them from Git history.
+
+## Installation
+
+```bash
+gem install ace-git-secrets
+```
+
+Install the required scanner and optional history-rewrite tool:
+
+```bash
+# macOS
+brew install gitleaks              # required scanner
+brew install git-filter-repo       # optional, for history rewriting
+
+# Arch Linux
+pacman -S gitleaks                 # required scanner
+pacman -S git-filter-repo          # optional, for history rewriting
+```
+
+Requires Ruby 3.2+ and `gitleaks` on your `PATH`.
+
+## 1. Run your first scan
+
+Start with the default scan:
+
+```bash
+ace-git-secrets scan
+```
+
+The command prints a summary to stdout and saves a reusable JSON report under `.ace-local/git-secrets/sessions/`. Keep
+the exact path printed by the command because both `revoke` and `rewrite-history` can reuse it.
+
+## 2. Read the report
+
+The saved JSON report includes token type, confidence, commit, file path, and raw token values needed for follow-up
+actions. When you want a shareable report for humans, run:
+
+```bash
+ace-git-secrets scan --report-format markdown
+```
+
+Use `--confidence high` when you want a narrower review, or `--since "30 days ago"` to limit large-repository scans.
+
+## 3. Revoke exposed tokens
+
+After a scan, revoke from the saved JSON report so you operate on the exact findings you reviewed:
+
+```bash
+ace-git-secrets revoke --scan-file .ace-local/git-secrets/sessions/abc123-report.json
+```
+
+Use `--service github` to narrow revocation to one provider, or `--token` when you already know the exact credential to
+invalidate.
+
+## 4. Preview history cleanup
+
+Always dry-run history rewriting first:
+
+```bash
+ace-git-secrets rewrite-history --dry-run --scan-file .ace-local/git-secrets/sessions/abc123-report.json
+```
+
+When the preview looks correct, run the real rewrite with the same scan file:
+
+```bash
+ace-git-secrets rewrite-history --scan-file .ace-local/git-secrets/sessions/abc123-report.json
+```
+
+`rewrite-history` creates backups by default and prompts before destructive changes unless you pass `--force`.
+
+## 5. Add a CI/CD gate
+
+Use the release gate to block publishes when secrets are still present:
+
+```bash
+ace-git-secrets check-release --strict
+```
+
+This is the simplest command to drop into release workflows or pre-publish checks.
+
+## Common Commands
+
+| Goal | Command |
+|------|---------|
+| Scan the full repository history | `ace-git-secrets scan` |
+| Save a Markdown report | `ace-git-secrets scan --report-format markdown` |
+| Scan recent history only | `ace-git-secrets scan --since "30 days ago"` |
+| Revoke tokens from a saved report | `ace-git-secrets revoke --scan-file .ace-local/git-secrets/sessions/abc123-report.json` |
+| Preview cleanup | `ace-git-secrets rewrite-history --dry-run --scan-file .ace-local/git-secrets/sessions/abc123-report.json` |
+| Block a release on findings | `ace-git-secrets check-release --strict` |
+
+## What to try next
+
+- Add whitelist rules in `.ace/git-secrets/config.yml` for known documentation examples or test fixtures
+- Load `ace-bundle wfi://git/security-audit` for a guided audit workflow
+- Load `ace-bundle wfi://git/token-remediation` for full scan, revoke, and rewrite guidance
+- Read [CLI Usage Reference](usage.md) for every option and output mode