Feature/exit menu item (#28)

Author: parameshjava

docs/superpowers/plans/2026-06-14-member-exit-policy.md

@@ -0,0 +1,98 @@
+# Full EMI prepayment: delete pending installments and close the loan
+
+**Date:** 2026-06-14
+**Status:** Approved
+**Area:** EMI loan model — `prepayLoan` server action
+
+## Problem
+
+When an EMI loan is fully prepaid (the advance covers the entire outstanding
+principal), the current code flips every remaining `scheduled` / `overdue`
+installment to `status = 'waived'`:
+
+```ts
+// src/lib/actions/emi.ts:212-219 (current)
+if (newOutstanding === 0) {
+  await supabase.from('loan_emi_schedule')
+    .update({ status: 'waived' })
+    .eq('loan_id', loanId)
+    .in('status', ['scheduled', 'overdue'])
+}
+```
+
+This is misleading. "Waived" means the obligation was *forgiven without
+payment*, but in a full prepayment the member **paid** the outstanding
+principal. The schedule then shows a row of "Waived" badges for installments
+the member actually settled in cash. Two further gaps:
+
+- The loan is **not** formally closed — `loans.status` stays `active` even
+  though the balance is zero.
+- A `partially_paid` installment's unpaid remainder is part of
+  `pending_principal`; the lump sum covers it, but nothing reconciles that row.
+
+## Goal
+
+After a full prepayment, the loan record should read like a clean, closed
+loan: only real installments remain on the schedule, the advance is captured
+as one transaction, and the loan is marked paid.
+
+## Design
+
+Change applies only to the **full-prepay branch** (`newOutstanding === 0`) of
+`prepayLoan` in `src/lib/actions/emi.ts`. The transaction insert (current
+line 193) and the optional bank-balance bump (line 207) are unchanged. Partial
+prepayment (`newOutstanding > 0`) is unchanged.
+
+New behavior when `newOutstanding === 0`:
+
+1. **Settle `partially_paid` rows from the lump sum.** The entered amount
+   equals `pending_principal`, which *includes* the unpaid remainder of any
+   partially-paid EMI. For each such row, set `principal_paid = principal_due`,
+   `status = 'paid'`, `paid_at = now()`. The row keeps its payment history and
+   stops reporting a dangling balance. (Without this, `loan_emi_balances` would
+   still show that remainder and the loan would not net to zero.)
+2. **Delete `scheduled` + `overdue` rows.** These never received a payment, so
+   they have no `loan_emi_payments` junction rows and the `ON DELETE RESTRICT`
+   FK (migration 038, line 74) does not block the delete. Paid /
+   partially-paid rows — which we keep — *do* have junction rows, which is an
+   additional reason the deletion scope is exactly `scheduled` + `overdue`.
+3. **Close the loan:** set `loans.status = 'paid'`.
+
+### What is kept vs deleted
+
+| Installment status | Action |
+| :----------------- | :----- |
+| `paid`             | kept untouched |
+| `partially_paid`   | kept, completed to `paid` (step 1) |
+| `scheduled`        | deleted |
+| `overdue`          | deleted |
+
+### Downstream — no changes required
+
+- `loan_emi_balances` (migration 040) sums `principal_due - principal_paid`
+  over non-`waived` rows. After the change all remaining rows are fully paid →
+  `pending_principal = 0`.
+- `loan-timeline-section.tsx` renders whatever rows exist; it simply shows
+  fewer rows. No badge logic change.
+- Authorization, `runAction` wrapper, `updateTag('dashboard')` /
+  `revalidatePath` calls remain as-is.
+
+## Verification
+
+- `recomputeAfterPrepayment` (pure helper) is untouched; its existing unit
+  tests still pass.
+- Add / extend a unit test asserting the full-prepay branch: paid rows kept,
+  partially-paid completed, scheduled/overdue gone, `loans.status = 'paid'`,
+  balance zero. (Confirm existing test harness for the action during
+  implementation; fall back to a focused test of any extractable pure logic if
+  the action itself is not unit-testable.)
+- Manual check on a seeded EMI loan: full prepay → timeline shows no "Waived"
+  rows, loan listed as closed/paid, KPIs show zero outstanding.
+
+## Out of scope
+
+- Partial prepayment behavior (unchanged).
+- The accrual loan model.
+- Backfill of loans already fully prepaid under the old waive logic. Noted as a
+  possible follow-up cleanup script; no historical rows touched here unless
+  requested.

docs/superpowers/specs/2026-06-14-emi-full-prepay-cleanup-design.md

@@ -0,0 +1,217 @@
+FCF Revised Rules
+
+This document consolidates the current operating rules of the Friends Cooperative Fund (FCF), superseding the earlier V1 and V2 rules.
+
+1. Member Classification
+
+The earlier distinction between Refundable and Non-Refundable members is discontinued. All members will be treated equally with respect to monthly contributions, benefits, loan eligibility, social support, and exit-related decisions.
+
+2. Monthly Contributions
+
+Each member shall make monthly contributions to FCF.
+
+The monthly contribution is ₹750 per member.
+
+Members are encouraged to enable auto-payment or standing instructions to avoid missed contributions.
+
+The monthly contribution amount shall be reviewed annually and may be revised based on inflation, fund requirements, and members’ financial circumstances.
+
+3. Contribution Discipline and Pending Contributions
+
+All members are expected to make contributions regularly and on time.
+
+Members with missed or pending contributions shall regularize the pending amount within 6 months.
+
+The Treasurer or Committee shall identify members with pending contributions and communicate the required regularization amount and timeline.
+
+Repeated delay or irregular contribution may be reviewed by the Committee and discussed with the concerned member.
+
+4. Fixed Corpus Fund
+
+FCF shall maintain a fixed corpus fund target of ₹5,00,000.
+
+The corpus target may be increased annually by 20% or adjusted based on inflation, fund growth, and member approval.
+
+Members shall continue contributing until the corpus target and future revised targets are achieved.
+
+The corpus fund shall be used carefully to ensure long-term sustainability of FCF.
+
+5. Loan Eligibility
+
+Loans may be provided to members based on fund availability, repayment capacity, loan purpose, and Committee/member approval.
+
+The maximum loan eligibility per member is capped at ₹2,00,000.
+
+Loan approval shall depend on available financial reserves at the time of request.
+
+Priority shall be given in the following order:
+
+1. Medical emergency loans
+2. Other urgent financial necessities
+3. Personal loans, subject to conditions and fund availability
+
+6. Medical Emergency Loans
+
+Medical emergency loans shall continue to be available even if the principal fund has not reached the fixed corpus target.
+
+Medical emergency cases may be treated separately with flexible conditions.
+
+Immediate health assistance shall primarily apply to immediate family members, including parents, spouse, and children.
+
+Requests involving siblings, in-laws, or other family members may be considered under the Social Fund or as an exception, based on member agreement.
+
+7. Personal Loans
+
+Personal loans should be treated as a last option after the member has explored other reasonable alternatives.
+
+Personal loans may be provided only when sufficient funds are available after protecting the medical emergency reserve and corpus requirements.
+
+Until the principal fund reaches the fixed corpus target, personal loans may be restricted or avoided, except in special cases approved by the Committee/members.
+
+Personal loans for repetitive personal reasons may be subject to stricter review, shorter repayment timelines, or rejection.
+
+Personal loans may be approved with specific conditions, including repayment within a shorter period such as 6 months, where applicable.
+
+8. Loan Repayment Model
+
+All loans going forward shall be operated on an EMI-based repayment model.
+
+Members taking loans shall repay through monthly EMI payments, with each EMI covering principal plus interest at the fixed rate of 8% per annum (Section 10).
+
+The borrower may be allowed to choose the repayment tenure, subject to the maximum tenure approved by FCF.
+
+Existing long-pending loans shall be reviewed, and borrowers may be requested to start or complete repayment if the loan has crossed a reasonable threshold.
+
+9. Loan Tenure
+
+The standard maximum loan tenure shall be 24 months.
+
+Any exception to this tenure, such as 18 months or 30 months, shall be approved separately based on the loan type, borrower situation, and fund condition.
+
+For personal loans, shorter repayment periods may be preferred.
+
+For medical emergency loans, flexible repayment conditions may be considered.
+
+10. Loan Interest Rate / Repayment Rate
+
+The loan interest rate is fixed at 8% per annum for all loans.
+
+This is the standard rate applied to every loan going forward, calculated on the loan within the EMI repayment model (Section 8).
+
+Repetitive personal loans may attract stricter repayment conditions (shorter tenure, additional review), subject to Committee/member approval, but the interest rate remains 8% per annum.
+
+11. EMI Calculation
+
+EMIs are calculated on the loan principal at the fixed interest rate of 8% per annum (Section 10) over the chosen repayment tenure, subject to the maximum tenure in Section 9.
+
+The exact monthly EMI for a given loan depends on its principal and tenure and shall be confirmed at the time of disbursement using the standard 8% per annum rate.
+
+12. Loan Disbursement Priority
+
+Loan requests shall be prioritized as follows:
+
+1. Medical emergencies
+2. Critical financial necessities
+3. Personal needs, subject to corpus availability and approval
+
+Loan approval shall also consider existing outstanding loans, pending contributions, member discipline, and overall fund position.
+
+13. Social Help Budget
+
+Social help shall operate on a monthly budget basis.
+
+The monthly social help budget is 20% of the contributions collected in that month. Any unused amount is carried forward to the following month.
+
+Requests for social help should be flagged early so that members and the Committee have enough time to review and respond.
+
+Social help usage shall be reviewed periodically based on actual historical spending and fund availability.
+
+14. Donations
+
+Donations received or donation-related decisions shall be handled transparently.
+
+Where applicable, donations may be added to the common fund, distributed equally among members, or used for social causes, based on member approval.
+
+A clear donation policy shall be finalized by the Committee and approved by members.
+
+15. Member Exit Policy
+
+A member willing to exit FCF shall formally express their decision to the Committee in writing. The exit settlement shall then be computed using the following steps.
+
+Step 1 — Settle outstanding obligations first.
+
+Before any refund is calculated, the exiting member shall clear all open obligations to FCF:
+
+* Any outstanding loan principal (and accrued interest) must be repaid or netted in full. A member cannot exit while holding an open loan against the fund.
+* Any pending or missed contributions must be regularized.
+
+The exit refund is computed only after these obligations are settled.
+
+Step 2 — Determine the member’s total eligible contributions.
+
+The eligible amount is the sum of all monthly contributions made by the member during their membership.
+
+Step 3 — Deduct the member’s equal share of shared costs.
+
+The total bad debts and the total donations paid out by FCF to date are treated as shared costs of the fund. These are divided equally across all members on a per-capita basis (1/N, where N is the total number of members), and the exiting member’s single equal share is deducted from their eligible contributions:
+
+```
+share of shared costs = (total bad debts + total donations) ÷ total number of members
+residual amount       = total eligible contributions − share of shared costs
+```
+
+Step 4 — Member decides what to do with the residual.
+
+Once the residual amount is determined, the exiting member may choose to either:
+
+1. Offer the residual amount to FCF as a donation to the common fund, or
+2. Withdraw the residual amount.
+
+The chosen settlement, the figures used (eligible contributions, total bad debts, total donations, per-capita share, and residual), and the member’s decision shall be documented clearly and approved by the Committee/members.
+
+16. Contribution Refunds
+
+Contribution refunds — whether on individual member exit (Section 15) or at closure of FCF — follow the same settlement basis: eligible contributions, less the member’s equal per-capita share of bad debts and donations, with all outstanding loans and pending contributions settled first.
+
+The member may choose to withdraw the residual amount or donate it to FCF / charity. The refund or donation process shall be documented clearly.
+
+17. Bad Debts and Donations as Shared Costs
+
+Bad debts (unrecovered loans, written-off amounts) and donations paid out are treated as shared costs of the fund and borne equally by all members on a per-capita basis.
+
+At the time of member exit or FCF closure, each member’s equal share of these shared costs shall be deducted from their refundable amount, as set out in Section 15.
+
+18. Account Management and Withdrawals
+
+FCF shall move towards joint account management wherever feasible.
+
+Financial bookkeeping responsibilities may be rotated among trusted members to improve transparency and shared responsibility.
+
+Quarterly financial statements shall be shared with all members.
+
+Any withdrawal above ₹50,000 shall require approval from at least two authorized signatories.
+
+Bank account credentials, access, and authorization rights shall be handled securely and responsibly.
+
+19. Financial Reporting
+
+The Treasurer or assigned Committee member shall share financial statements with all members on a quarterly basis.
+
+The statement shall include:
+
+* Opening balance
+* Monthly contributions received
+* Pending contributions
+* Loans disbursed
+* Loan repayments received
+* Interest received
+* Social help or donations paid
+* Expenses incurred
+* Closing balance
+* Outstanding loans
+
+20. Periodic Review Meetings
+
+FCF shall conduct quarterly or half-yearly catch-ups to review fund status, loan performance, pending contributions, social help, donations, and rule improvements.
+
+Rules may be amended based on member feedback, fund condition, and majority approval.