docs(kilo-pass): document current implementation rules

[jeanduplessis]

Summary

Document current Kilo Pass behavior and known implementation limits as a retrospective source-of-truth draft.

Why this change is needed

Kilo Pass behavior is spread across billing, issuance, mobile-store, projection, and UI paths. Future work needs one code-faithful reference that distinguishes current guarantees from stronger behavior that has not been implemented.

How this is addressed

• Record current provider coverage: Stripe monthly and yearly flows, App Store monthly flow, and Google Play representation without exposed verified purchase ingress.
• Document implemented subscription selection, threshold ownership, streak accounting, welcome-promo decisions, duplicate-card handling, scheduled changes, expiry, and audit behavior.
• Move stronger guarantees into Not Yet Implemented and record the adjacent Subscription Center unpaid presentation mismatch.

Human Verification

• Compared the spec against current Kilo Pass libraries, router paths, shared projection utilities, mobile-store flow, and focused regression tests.
• Ran an independent read-only logic review after the rewrite and corrected its findings.

Reviewer Notes

Human Reviewer Flags

• This is a retrospective source-of-truth draft. Code remains authoritative while alignment settles.
• Review the documented implementation limits in Not Yet Implemented; they are intentionally not presented as current guarantees.
• Kilo Pass and Subscription Center currently treat unpaid differently. The mismatch remains documented for follow-up.

[kilo-code-bot]

WARNING: Rule 6 description is incomplete — the active-row check also requires a non-ended status

The spec says the active-row check is "the first user subscription row with a null ended marker", but store-subscription-completion.ts:472-478 also applies !isStripeSubscriptionEnded(activeSubscription.status) before throwing. A row with ended_at = null but a status of canceled, unpaid, or incomplete_expired is NOT treated as a blocking active subscription. The dual condition should be documented:

Store purchase completion MUST use its own active-row check: the first user subscription row with a null ended marker and a non-ended provider status.

This is advisory only as the code is authoritative during alignment.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Executive Summary

The new commit is purely a line-wrap reformat of .specs/kilo-pass.md; the one substantive inaccuracy in Rule 6 (omitting the non-ended status condition from the active-row check description) remains unresolved.

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.specs/kilo-pass.md	121–122	Rule 6 describes the store active-row check as "the first user subscription row with a null ended marker" but the implementation (store-subscription-completion.ts:472–478) also requires !isStripeSubscriptionEnded(status). A row with ended_at = null but a terminal status (e.g. canceled) is not blocked by the ended-marker check alone. The spec should add "and a non-ended provider status" to accurately reflect the two-part condition.

Other Observations (not in diff)

All other key spec claims verified against source code with no discrepancies:

Claim	Evidence
Subscription selection order (Rule 2)	state.ts:89–106, kilo-pass-bonus-projection.ts:107–118
Monthly ramp formula min(40%, 5%+5%*(n-1)) (Rule 13)	kilo-pass-bonus-projection.ts:29–31,67–70
Welcome promo cutoff 2026-05-07T00:00:00Z (Rule 16)	constants.ts:14
Duplicate-card gate on every invoice.paid (Rules 51–55)	stripe-handlers-invoice-paid.ts:500, card-fingerprint-gate.ts:85–137
Streak scan cap = 36 months (Rule 46)	subscription-accounting.ts:34
Yearly streak stored as 0 (Rule 50)	stripe-handlers-invoice-paid.ts:633
5 fingerprint claim types (Definition)	schema-types.ts:40–46
3 ended provider statuses (Definition)	stripe-subscription-status.ts:2

Files Reviewed (1 file)

• .specs/kilo-pass.md — 1 issue (reformatted only in new commit; issue carried forward)

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-4.6-sonnet-20260217 · 583,861 tokens}

_{Review guidance: REVIEW.md from base branch main}