feat: nightly AI scanner workflows (code review, docs, autonomous scanner)

[Tony363]

Summary

Adds 3 scheduled AI-powered workflows (split from #683, PR B per review feedback):

• nightly-code-review: Daily code improvements via Claude ($3-8/run, 3 AM UTC)
• nightly-docs-update: Daily documentation sync ($1-3/run, 4 AM UTC)
• autonomous-code-scanner: Multi-pass scanner with $100/run budget cap (2 AM UTC)

Supporting files

• .github/scripts/anthropic_helper.py — Anthropic API wrapper
• .github/scripts/generate-type-hints.py + apply-type-hints.py
• .github/scripts/generate-docstrings.py + apply-docstrings.py
• .github/prompts/nightly-code-review.md + nightly-docs-update.md

Security hardening

• All actions pinned to commit SHA
• GITHUB_TOKEN used for all PR creation (no PAT_TOKEN)
• Secret validation uses env-block pattern
• Protected file patterns block installers/, dream-cli, config/

Note: AI-generated draft PRs (from scanners, nightly reviews) use GITHUB_TOKEN
for PR creation. By design, these PRs won't have CI checks run automatically.
A maintainer must interact (push, close/reopen, or label) to trigger CI.

Setup

Only one secret needed: ANTHROPIC_API_KEY

All workflows support workflow_dispatch with dry_run option for testing.

Cost estimate

Monthly: $270–$2,130 depending on scanner depth. Start with P0+P1 only.

Depends on

• feat: consolidated AI code review + issue triage + release notes #691 (PR A) ships first

Test plan

• CI checks pass
• actionlint validates all workflow YAML files
• No mutable action tags or PAT_TOKEN references
• Manual workflow_dispatch with dry_run: true succeeds

---

🤖 Generated with Claude Code

[Lightheartdevs]

Audit Review

Good architecture — no user-controlled input in prompts, three-layer protected file enforcement, budget caps, SHA-pinned actions, GITHUB_TOKEN for all PR creation. However, three blocking issues:

Blocking: npx -y @anthropic-ai/claude-code is not version-pinned

Both nightly-code-review.yml and nightly-docs-update.yml install Claude Code via npx -y @anthropic-ai/claude-code with no version specifier. This always fetches latest from npm. A supply chain compromise of the npm package gets arbitrary code execution with ANTHROPIC_API_KEY and GITHUB_TOKEN.

Fix: Pin to a specific version, e.g., npx -y @anthropic-ai/claude-code@0.2.72

Blocking: Cost risk — disable cron triggers initially

Estimated $270-2,130/month on daily schedules. The autonomous scanner alone can hit $100/run — at daily that's potentially $3K/month.

Fix: Change schedule triggers to workflow_dispatch only. Run manually for a few weeks to observe actual costs before enabling cron.

Blocking: Patch collision in create-prs job

The create-prs job applies formatting, type-hints, and documentation patches sequentially on the same checkout, then creates separate PRs per category. But peter-evans/create-pull-request branches from the current accumulated state, so:

• Formatting PR: clean (only formatting changes)
• Type-hints PR: contains formatting + type-hints
• Docs PR: contains formatting + type-hints + docs

Fix: Reset the checkout between each category (git checkout -- . or re-checkout) before applying each patch.

Medium: Deprecated ::set-output

generate-docstrings.py and generate-type-hints.py use ::set-output which is deprecated. Use >> $GITHUB_OUTPUT instead.

Required: Remove gpu.py change

Same fix as #691 and #693. PR #715 already merged this. Remove to avoid conflicts.

Good

• No user-controlled input in any prompt (prompts from .github/prompts/, inputs are git log and AST)
• Three-layer protected file enforcement (prompt + post-hoc revert + secret scan)
• Budget cap ($100/run for autonomous scanner)
• All actions SHA-pinned
• GITHUB_TOKEN for PR creation (no recursion)
• Schedule-only triggers — forks can't trigger
• Deduplication checks for existing open PRs