itr_form union widened to ITR-1 / ITR-2 / ITR-3 / ITR-4

Decision

Widen the persisted tax_reviews/{ay}.itr_form union from "ITR-1" | "ITR-2" to "ITR-1" | "ITR-2" | "ITR-3" | "ITR-4". Widen the shared inferItrForm return type to match and extend its decision matrix to a 4-way discriminant driven by PGBP signals:

presumptive-only (44AD/ADA/AE) & no CG & no >1 HP & no foreign & income ≤ ₹50L → ITR-4
books OR partner-in-firm OR (presumptive + any ITR-2 disqualifier)         → ITR-3
CG / foreign / >1 HP / income > ₹50L (no PGBP)                             → ITR-2
else                                                                        → ITR-1

inferItrForm remains the single source of truth. The engine picks the form; the user never picks (per what-we-sell).

Why

The Phase-F decision (2026-07-09-phase-f-recompute-itr-observability) persisted itr_form as "ITR-1" | "ITR-2" because the tax engine at the time only handled those two forms. Reintroducing self-file for individuals (2026-07-25-self-file-reintroduced-itr1-4) requires the engine to classify PGBP-bearing returns and route them to ITR-3 or ITR-4. A narrower enum blocks the schema layer before any rule or emitter change lands.

Only the enum shape of the Phase-F decision is superseded — the observability tile, the recomputeExpenseReview / recomputePortfolioReview callables, and the unmapped_paise KPIs from that ADR stay canonical.

Impact

• packages/shared/src/schemas/tax-review.ts — widen itr_form: z.enum(["ITR-1", "ITR-2"]).optional() to the 4-value union. Existing documents with the 2-value shape remain valid — no migration needed.
• packages/shared/src/rules/v1/income-summary.ts — widen inferItrForm return type and extend the decision tree with PGBP branches; add pgbp_paise and PGBP signals to IncomeSummary.
• packages/shared/src/rules/v1/orchestrator.ts — pass PGBP signals into inferItrForm; persisted value is the new union.
• apps/website/src/utils/itr-form.ts — widen the client return type; keep delegating to the shared inferrer.
• packages/shared/src/schemas/consult-request.ts — ITR_FORM_CODES already includes ITR-3/4; no schema change, but downstream consumers (ca-application.ts, ca-pricing.ts) already have itr1..itr4 rows.
• apps/functions/src/tax/render-tax-pdf.ts — new PGBP section for ITR-3/4 handoff PDFs.
• Related concepts / entities: pillar-tax, pgbp-income, audience-salaried-filer, what-we-sell.

This decision does not itself introduce the PGBP rule modules, the emitter, or the UI — those land in the Phase 1 / Phase 2 implementation ADRs. It records the schema-level widening as a prerequisite.

Status

Active.

Sources

• Plan: /Users/rsf/.claude/plans/system-instruction-you-are-working-zany-cloud.md
• Companion: 2026-07-25-self-file-reintroduced-itr1-4
• Enum scope supersedes: 2026-07-09-phase-f-recompute-itr-observability (item 2 only)