Add doc-comment audit workflow

[LasmarKhalifa]

Part of #1008

In a nutshell: a Roast workflow that guards against doc-comment drift. It reads the doc comments across the codebase, 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.
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).
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 here: https://app.graphite.com/github/pr/Shopify/roast/1034

[LasmarKhalifa]

• Add doc-comment audit workflow #1031 👈 (View in Graphite)
• main

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