docs: record binding readiness promotion

[onutc]

Summary

A deployment can cache an installation as provisioning even after the live Spritz binding is ready.
This doc records the generic rule: refresh the binding before rejecting channel traffic or runtime identity exchange, and promote the cached status only when the target and desired revision match.
The wording stays deployment-agnostic and does not depend on any specific provider or agent system.

What Changed

The binding target reconciliation doc now covers cached status promotion.
It explains when a deployment should record a ready binding and when it must keep reporting provisioning.

• Added desired-revision matching to the readiness rule.
• Added a cached status promotion section.
• Updated pseudocode to record the applied runtime revision.
• Added test cases for stale cached status.

Testing

This is documentation-only.

• npx -y @simpledoc/simpledoc check docs/2026-04-25-binding-target-reconciliation.md

Risks

Risk is low because this only changes documentation.
The main concern was keeping the doc generic, so examples use neutral deployment and binding terms.

[gitrank-connector]

👍 GitRank PR Analysis

Score: 5 points

Metric	Value
Component	Other (1× multiplier)
Severity	P3 - Low (5 base pts)
Final Score	5 × 1 = 5

Eligibility Checks

Check	Status
Issue/Bug Fix	❌
Fix Implementation	✅
PR Documented	✅
Tests	✅ (not required)
Lines Within Limit	✅

Impact Summary

This PR enhances documentation for binding target reconciliation by clarifying when deployments should promote cached installation status from 'provisioning' to 'ready'. It adds guidance on avoiding stuck states where deployment cache diverges from live binding state, and includes updated pseudocode and test case recommendations. The changes are purely informational and do not modify any executable code.

Analysis Details

Component Classification: This PR modifies documentation only, with no code changes to any specific feature or system component. It falls under the OTHER category as miscellaneous/documentation changes.

Severity Justification: This is a documentation-only PR that clarifies existing behavior and best practices. While it addresses an important operational concern (cached status promotion), it does not fix a broken feature, prevent data loss, or resolve a security issue. It represents minor polish and guidance documentation.

Eligibility Notes: Tests are not required for documentation-only changes. The PR has no associated issue reference but clearly documents an operational pattern. The fix_implementation check passes because the documentation additions align with the PR title and description. The PR is well-documented with clear summary and testing verification (documentation linting).

---

Analyzed by GitRank 🤖