Add partial / milestone-split fund release to release_funds in src/lib.rs

[1nonlypiece]

📌 Description

Today release_funds in src/lib.rs is strictly all-or-nothing: it
transfers the entire vault.amount to success_destination and flips
status to Completed. A creator who commits 10,000 USDC against a milestone
cannot release a partial tranche when only part of the milestone is met — the
funds are locked until the full deadline path or a full release fires.

This issue introduces partial / tranche-based release so a vault can pay out
a fraction of its escrowed balance and remain Active for the remainder, then
naturally complete when the balance reaches zero.

Goal: let release_funds accept (or a new release_partial expose) a
release_amount, debit the vault's remaining balance, route it to
success_destination, and only transition to Completed once the balance is
fully drained.

🎯 Requirements and Context

• Must be secure, tested, and documented — this is fund-settlement logic.
• Track a released_so_far (or remaining) field on ProductivityVault; never
  allow cumulative releases to exceed amount (use checked arithmetic).
• Preserve existing behaviour: a single full-amount release must still complete
  the vault and pass current tests/lifecycle.rs expectations.
• Keep the existing authorization model (creator.require_auth()) and the
  validated-or-deadline gate intact.
• Reject partial release on non-Active vaults with Error::VaultNotActive.

🛠️ Suggested Execution

1. Fork the repo and create a branch

git checkout -b feature/partial-milestone-release

2. Implement changes

• Contract: extend src/lib.rs
  • Add a remaining: i128 field to ProductivityVault (default = amount).
  • Add release_partial(env, vault_id, usdc_token, release_amount) using
    checked subtraction; transition to Completed only when remaining == 0.
  • Emit a stable funds_released_partial event carrying (vault_id, amount, remaining).
• Tests: add cases to tests/lifecycle.rs plus a new tests/partial_release.rs.
• Docs: add docs/PARTIAL_RELEASE.md with a worked numeric example; cross-link
  from README.md.
• Add NatSpec-style /// doc comments on every new public function.
• Validate security: rounding/remainder can never let total payouts exceed amount.

3. Test and commit

• Run cargo test.
• Cover edge cases: release of 0, release > remaining, exact final tranche,
  release on cancelled/failed vault, overflow attempt on accumulation.

Example commit message

feat: partial milestone-split release in release_funds with tests and docs

✅ Guidelines

• Minimum 95% test coverage on new/changed lines.
• Clear, reviewer-friendly documentation (formula + worked example).
• No regressions on existing lifecycle snapshots.
• Timeframe: 96 hours.

🏷️ Labels

type-feature · area-contracts · type-security · type-testing ·
MAYBE REWARDED · GRANTFOX OSS · OFFICIAL CAMPAIGN

💬 Community & Support

• Join the Disciplr contributor Discord to coordinate, ask questions, and get
  unblocked fast: https://discord.gg/xvNAvMJf
• Please introduce yourself before you start so we can avoid duplicate work,
  pair you with a reviewer, and merge your PR quickly.

[dangelo352]

I can take this. I’ll add a tracked remaining balance plus a focused release_partial flow, preserve existing release_funds as full settlement, reject zero/over-remaining/non-active releases, emit partial-release events, and document the partial payout lifecycle.

[leocagli]

I'd like to work on this issue, please assign me so I can begin implementation.

[alanamind7]

Submitted PR for #218: #263

Validation: cargo fmt plus full test suite passed on Rust 1.88.0.

[grantfox-oss]

🦊 GrantFox — @dangelo352 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #218)
2. Your PR will be reviewed by the Disciplr-Org maintainers

Good luck! Track your progress on GrantFox.