docs: Explain optional repair verification

[lokesh0186]

• This PR introduces breaking change.
• This PR fixes a bug.
• This PR adds new functionality.
• This PR enhances existing functionality.

Description of your changes

What

Add an optional README example beside terraform_checkov for repositories that keep a trusted before/after Terraform repair pair. It explains how a team can compare full Checkov JSON reports itself, then links the released IaC-Guard-V 1.0 recipe for teams that prefer a packaged check for one declared target. Trivy's passing results and custom checks are acknowledged as other building blocks. This PR changes documentation only; it does not add a hook or dependency to pre-commit-terraform.

Closes #1029.

Why

Checkov's baseline is useful for finding new failures, but a zero baseline exit does not show that a particular existing finding was repaired. A reviewer needs to see the selected check fail before and pass afterward on the same resource, and an inconclusive scan must not count as success. A small project-owned script over full Checkov reports can do this for a controlled case. Teams taking that route also need to handle missing or duplicate targets, skips, parsing errors, and failed scans. For supported Checkov evidence, the linked IaC-Guard-V recipe packages those checks, binds the declared target to the before and after snapshots, and retains a report with the result. Keeping it optional gives teams a concrete choice without changing this project's default hooks.

How can we test changes

pre-commit run --files README.md and git diff --check passed locally. The local pre-commit setup needed SSL_CERT_FILE=/etc/ssl/cert.pem to install its Node environment.

For the linked recipe, I ran the released IaC-Guard-V 1.0.0 wheel with Checkov 3.3.0 in separate environments. The synthetic EBS repair returned VERIFIED/0; unchanged, deleted, suppressed, malformed, and wrong-resource candidates did not pass. The recipe records the author-run checks. These are author-run results, not a pre-commit-terraform maintainer run.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: antonbabenko/pre-commit-terraform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 41b18d04-22e9-40a1-919d-63466a4f0321

📥 Commits

Reviewing files that changed from the base of the PR and between 80c8033 and 9ef56ec.

📒 Files selected for processing (1)

• README.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• Documentation
  • Added an optional workflow for checking whether a declared Checkov repair changes the specified check and resource from failed to passed between scans.
  • The guide explains how skipped checks, parsing errors, and missing results affect verification, and notes that failed or inconclusive checks return a nonzero result.
  • Clarifies that verification requires trusted reports and an exact target, does not validate every resource or the rule itself, and is not included in the project’s hook manifest.

Walkthrough

The README adds an optional workflow that compares Checkov JSON reports before and after a scan to verify one declared repair. It documents setup, inconclusive results, failure conditions, and scope limits. The workflow is external and is not included in the project’s hook manifest.

Changes

Repair Verification Documentation

Layer / File(s)	Summary
Document the external verification recipe README.md	The README explains the required failed-to-passed result for the same check and resource, report handling, setup, failure conditions, and scope limits.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Suggested reviewers: maxymvlasov

Merge Risk: ⚪ Minimal · up to 9ef56

The optional recipe’s documented behavior and external status are supported. No actionable merge risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to 9ef56

The change affects 1 system.

Changed systems: README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: Adds documentation for an optional, external recipe to verify a single declared repair by comparing full Checkov JSON reports before and after a scan. It describes the required failed-to-passed result for the same check and resource, handling of inconclusive report cases, recipe setup and failure result, and its scope limitations; the hook is not included in this project’s manifest.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the optional repair-verification documentation added to the README.
Description check	✅ Passed	The description explains the documentation change, its purpose, and the reported tests. It is directly related to the changeset.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}