Add comment audit workflow

[LasmarKhalifa]

Part of #1008

In a nutshell: a Roast workflow that guards against doc-comment and inline comment drift. It reads the comments across the codebase (or any passed target), has an agent check each one against the real implementation, and opens a single PR fixing the stale ones. Read-only by default; it opens a PR only when run with -- apply.

How it works (one cog per phase):

1. Enumerate parses each in-scope file with Prism and extracts atomic units: each contiguous # prose block sitting above a definition (class, module, method, attr, constant), plus its RBS signature, as well as inline comments.
2. Verify fans out across units in parallel, one agent per unit (Claude Sonnet), judging the comment against the actual code and returning a structured verdict (factual? confidence? suggested fix?).
3. Plan classifies each verdict: factual, stale-and-auto-fixable (confident with a safe fix), or low-confidence (report only). (Current threshold is set at 0.8, but this should be adjusted over time).
4. Apply (only with -- apply) splices the fixes in and opens one draft PR on top of the current branch, gated by a check that requires a clean, pushed, even working tree so the PR diff is only the doc fix.
5. Summary prints the findings.

Scope defaults to lib/roast plus the rbi shims; pass files or directories as targets to narrow it.

The workflow is heavily commented inline, so that a reader can follow the enumeration and classification logic without having to reverse-engineer it.

Example test run scoped to one file (lib/roast/cog/output.rb) here: https://app.graphite.com/github/pr/Shopify/roast/1037

[LasmarKhalifa]

• Add comment audit workflow #1031 : 2 dependent PRs (#1034 , #1037 ) 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.