feat(2): Add ThenEnsure / ThenEnsureAsync pass-through validation helpers

[Copilot]

• Inspect PR state and confirm the README conflict is still reported on GitHub
• Compare /home/runner/work/fail-or/fail-or/README.md on this branch with main
• Make the smallest README-only merge resolution needed for the conflicting hunk
• Re-run verification after the README update
• Run final automated review/security checks for the documentation change
• Reply on the PR comment with the commit that resolves the conflict

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add ThenEnsure / ThenEnsureAsync pass-through validation helpers</issue_title>
<issue_description>Add success-only guard helpers that run another FailOr check and keep the original TSource when that check succeeds.

A checklist item in this issue is only complete when the implementation, relevant tests, and required documentation updates for that item land together in the same change. ErrorOr<R> from the original request maps to repo-native FailOr<R>, and “all arities” here means mirroring the existing direct and lifted Then family without adding parameterless, CancellationToken, or ValueTask overloads.

API

• FailOr<TSource> ThenEnsure<TResult>(Func<TSource, FailOr<TResult>> ensure) for FailOr<TSource>
• Task<FailOr<TSource>> ThenEnsureAsync<TResult>(Func<TSource, Task<FailOr<TResult>>> ensureAsync) for FailOr<TSource>
• Task<FailOr<TSource>> ThenEnsure<TResult>(Func<TSource, FailOr<TResult>> ensure) for Task<FailOr<TSource>>
• Task<FailOr<TSource>> ThenEnsureAsync<TResult>(Func<TSource, Task<FailOr<TResult>>> ensureAsync) for Task<FailOr<TSource>>

Expected Behavior

• Success plus successful ensure returns the original success value unchanged
• Success plus failed ensure returns the ensure failures as FailOr<TSource>
• Failed source short-circuits without invoking the delegate
• Null delegates throw ArgumentNullException
• Async overloads throw ArgumentNullException when the delegate returns null
• Delegate exceptions are not wrapped

Documentation

• XML documentation with exceptions and example for each public function
• README.md chaining/validation examples updated
• docs/api-reference.md updated

Verification

• Direct overload tests for pass-through success behavior
• Direct overload tests for ensure-produced failures
• Direct overload tests for failed-source short-circuiting
• Direct overload tests for null delegate handling
• Direct async overload tests for null returned task handling
• Lifted overload parity tests against direct behavior
• dotnet csharpier format run on changed files
• dotnet test --solution fail-or.slnx passes
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add ThenEnsure / ThenEnsureAsync pass-through validation helpers #2

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[mark-pro]

There is a conflict that needs to be resolved, can you fix the conflicting file? @copilot

[Copilot]

There is a conflict that needs to be resolved, can you fix the conflicting file? @copilot

Resolved in 1ead18d. I merged current main into the branch, kept the README conflict resolution in place, and the PR now shows as mergeable/clean.