Define an idempotent failed-block writing policy

[claell]

Summary

• Preserve retained failed-block raw source unchanged by default.
• Offer explicit annotate and fail-closed raise policies.
• Keep opt-in annotations idempotent across repeated parse/write cycles.
• Reject unknown policies and continue rejecting failed blocks without raw source.
• Document why normal mutable blocks still serialize from model state rather than cached raw text.

Closes #588.

Dependency and commit structure

The first commit is the same focused configured-comment fix already represented by #530 / draft PR #566. It is included so the policy branch is executable against current main. The policy and annotation-idempotence changes are the second and third commits. After #566 merges, this branch should be rebased to remove the prerequisite diff.

Validation

• Focused failed-block writer and round-trip tests under warnings-as-errors: 8 passed before the annotation follow-up, followed by the dedicated annotation-idempotence regression passing.
• Complete upstream suite: 2,583 passed, 12 skipped, with the four existing deprecation warnings in tests/test_entrypoint.py.
• Complete pre-commit hook suite: passed.

Review note

The proposed default changes from generated annotation to exact raw preservation. This is a deliberate integrity choice, but it is user-visible and needs maintainer review. The previous behavior remains available explicitly as annotate; strict consumers gain raise. There is intentionally no discard policy.

The implementation also avoids adding a second terminal newline to failed raw source. Without that detail, even annotate changes the failure's line count and cannot recognize its own diagnostic on the next cycle.

AI assistance

This pull request was prepared with ChatGPT Codex using GPT-5.6 Sol with high reasoning effort. Codex assisted with policy design, dependency isolation, regression analysis, newline edge-case repair, and validation. Automated validation is not a substitute for maintainer review.