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.

[MiWeiss]

Hi @claell — same note across all of your July 16 issues and PRs (#567–#597), apologies for the repetition.

Closing this. Passing CI isn't evidence the underlying claim is real — it just means generated tests match generated code. The batch's timing, structure, and forward-referenced numbers point to this being AI-generated rather than manually found and checked, and reviewing it properly would take more effort than a targeted pass over the parser myself.

If this fixes something you actually hit: open a small, human-verified PR against a reopened issue with a real repro, and I'll review it in good faith. Any nontrivial design or API choice needs to be discussed and agreed first, not decided inside a PR. Please disclose and verify AI-assisted work before submitting going forward.