feat(regenerate): batch path via Anthropic Message Batches API

[silversurfer562]

Summary

Adds opt-in attune-author regenerate --batch for cost-saving bulk help regen via Anthropic's Message Batches API (~50% cost vs synchronous per-call pricing). Submit-and-detach UX with a --resume partner that polls + splices results when ready.

Sequenced as item (3) from the 2026-05-08 enhancements briefing. Closes the briefing's three-item sequence (after attune-author#20 for skill-export and attune-rag#11 for native citations).

Spec: specs/author-batch-maintain/{requirements,design,tasks}.md.

CLI surface

$ attune-author regenerate --batch
Submitted batch msgbatch_xyz (35 requests, model claude-sonnet-4-20250514).
Estimated completion: ~6 min (Anthropic 24h SLA).

Run  attune-author regenerate --resume   to splice results when ready.

# ... lunch ...

$ attune-author regenerate --resume
Batch msgbatch_xyz ended. Regenerated 32 feature(s). Failed: rag, smart-test

Mutex-enforced flag set: --batch | --resume | --status | --cancel. Modifiers: --force (with --batch: overwrite pending state file), --json (with --status: cron-friendly output).

Resume ergonomics (the user's emphasis)

• No batch ID required — --resume reads .help/.batch-state.json automatically.
• Bare regenerate prints a hint when a state file exists; never auto-resumes silently.
• Resume-after-timeout works — state file kept on poll-loop timeout, next --resume picks up cleanly.
• --status is one-shot — query without committing to a wait. --json for cron parsing.
• --cancel is one-shot — call SDK cancel + remove state file.
• Stale-state recovery — 29-day retention check (matches Anthropic) surfaces a clean cleanup hint instead of crashing on a 404.
• Multi-batch guard — --batch refuses to overwrite an existing state file unless --force is passed.

What landed

• attune_author.doc_gen._anthropic_batch — SDK wrapper with submit_batch / poll_batch, typed BatchPolishRequest / BatchPolishResult, adaptive timeout (min(30min, max(5min, 60·N/20))), SIGINT-cancels-and-reraises.
• attune_author.maintenance_batch — submit_maintenance_batch / resume_maintenance_batch / status_maintenance_batch / cancel_maintenance_batch, plus BatchState schema and state-file lifecycle.
• attune_author.polish.build_polish_prompt — extracted prompt-building helper. Both paths build byte-identical prompts.
• attune_author.generator.prepare_polish_phase / apply_polish_results — extracted Phase 1 (render) and Phase 3 (write) helpers. Synchronous path now calls them too. Single source of truth for rendering.
• docs/regenerate-batch.md — when to use which path, fallback behavior, env-var overrides, cancel semantics, stale-state recovery.

Tests

• +57 new unit tests, all passing:
  • 19 for the SDK wrapper layer (test_anthropic_batch.py) — golden-fixture parser, payload shape, full poll-loop state matrix, SIGINT cancel, adaptive timeout
  • 22 for orchestration (test_maintenance_batch.py) — state file lifecycle, submit/resume/status/cancel, per-feature failure isolation, timeout-keeps-state, parity test (sync vs batch produce identical files)
  • 16 for CLI (test_cli_batch.py) — argparse mutex, all four modes, --json shape, bare-command pending-batch hint
• +1 opt-in live integration test at tests/integration/test_batch_live.py, gated on ANTHROPIC_API_KEY + RUN_LIVE_BATCH=1. Tagged @pytest.mark.live. Default-skipped; ~$0.02/run.
• Full suite: 670 passed, 32 skipped (live + pre-existing skill-export integration).
• Ruff clean on all touched files.

Verification gate

V1 (Anthropic SDK class names) verified live against SDK 0.89.0:

• Resource path is client.messages.batches
• MessageBatch exposes processing_status, request_counts, expires_at, cancel_initiated_at, results_url
• MessageBatchIndividualResponse carries custom_id + result (discriminated union: Succeeded / Errored / Expired / Canceled)

Pinned in code; recorded fixture at tests/golden/batch_response.json regression-tests the parser.

Test plan

• CI green on all matrix rows (Linux/macOS/Windows × Python 3.10–3.13)
• (Optional, on user) Run RUN_LIVE_BATCH=1 pytest tests/integration -m live to exercise end-to-end against the real Anthropic API

🤖 Generated with Claude Code