ESPP Tax U.S. federal characterization for ESPP sales.
v0.2.8

Latest changes

v0.2.8 2026-10-03

  • Add a review agent so catalog facts stay aligned with the hub.

v0.2.7 2026-09-27

  • Render Architecture diagrams as charts instead of Mermaid source.

v0.2.6 2026-09-27

  • Show a restored calculator report on the App tab instead of hiding it.
  • Add an in-browser iOS/Android calculator simulation and remove the project ship-to-main agent.

v0.2.5 2026-09-27

  • Keep calculator drafts across pages and label architecture assets on the arrows.

v0.2.4 2026-09-27

  • Add an Architecture page next to Vision with logical and physical production diagrams.

v0.2.3 2026-09-27

  • Add a header Calculator home link and let users close release notes without leaving the page.

v0.2.2 2026-09-27

  • Add a header Vision page so users can read the product contract without leaving the app.

v0.2.1 2026-09-27

  • Show the shipped release version in the header and bump it automatically on every merge to main.
  • Add a washed office photo behind the calculator and describe the UI in this app’s own tokens only.
  • Give the calculator a custom look and keep living docs current.
  • fix: update TemplateResponse calls for Starlette 1.0+
  • fix: improve Vercel config for logging and build-time import check
  • fix: make espp_tax importable on Vercel serverless
  • ci: add GitHub Actions workflow to run pytest
  • Add script to publish Vercel-ready code to ESPP_TAX_VERCEL repo
  • Add Vercel deployment configuration for FastAPI web UI
  • Add ESPP Tax workspace skills
  • Prevent scroll from changing number inputs and clarify sale price quick-picks.
  • Add FastAPI + Jinja2 + HTMX web UI for ESPP tax calculator.
  • Add real-world tax inputs and dollar estimates for ESPP sales.
  • Initial ESPP_TAX scaffold for ESPP tax calculations.
Educational only · not tax advice

Product contract

Vision and requirements

Summary of the living spec. Last updated 2026-09-27.

Read the full document on GitHub

Vision

Help someone with ESPP shares understand **how a purchase-and-sale is characterized** for U.S. federal tax purposes — ordinary income vs. capital gain, qualifying vs. disqualifying disposition, basis, and a **simplified dollar estimate** — before they talk to a tax professional.

The product is an educational planner, not a filing tool and not tax advice.

Who it is for

  • ESPP participant (employee): Enter one lot (offer, purchase, sale, rates) and see a readable report
  • Library consumer: Call `espp_tax` from Python without the web UI
  • Maintainer / agent: Keep tax math in one place and keep this document honest

In scope

  1. Model a **single purchase lot** and a **sale of some or all** of those shares.
  2. Apply Section 423 holding rules (2 years from offer start, 1 year from purchase).
  3. Characterize ordinary income, cost basis, and capital gain using the IRS **lesser-of** rule on qualifying dispositions.
  4. Optionally estimate tax dollars from user-supplied **marginal** rates.
  5. Make the report verbose enough to audit: inputs, derived prices, disposition, characterization, narrative.
  6. Stay deployable as a small FastAPI app on Vercel with no accounts or stored user data.

Out of scope

  • A complete Form 1040, Schedule D, Form 6251, or AMT credit worksheet
  • NIIT, wash sales, loss netting against ordinary income
  • Multiple lots, FIFO, or specific identification
  • ISO / NSO overlap or payroll withholding detail
  • State-specific ESPP statutes beyond one marginal state rate
  • Persistence, auth, or multi-user workspace
  • Live market quotes or brokerage imports

Shipped requirements

21 functional, 7 non-functional, and 13 UX requirements are marked Shipped. IDs and status live in the GitHub document.

Constraints

  • Educational disclaimer must remain visible (header and footer).
  • Plan documents and employer W-2 treatment can differ from the model; the UI must not imply otherwise.
  • Holding-period “2 years” is implemented as 730 days from offer start.