Document company-director NI (annual cumulative basis) (#721)

[vahid-ahmadi]

Summary

• NI thresholds for company directors #721 reported that there was no input flag for company-director NI thresholds. Investigated; the situation is more nuanced than "add a flag":
  • HMRC's annual cumulative basis for directors exists to prevent the bonus-timing avoidance route under monthly NI rules. Annual thresholds are applied to YTD earnings.
  • PolicyEngine UK already computes NI as an annual quantity (the Class 1 formula reads weekly thresholds, converts to monthly via WEEKS_IN_YEAR / MONTHS_IN_YEAR, then sums to an annual figure). For any user inputting annual employment_income, the model's annual NI matches HMRC's director annual cumulative figure — no divergence in microsimulation.
  • Three edge cases where a dedicated director path would matter (irregular pay timing, mid-year director status changes, multiple employments) are surface area for the household calculator, not microsimulation.
• New docs page at docs/book/programs/gov/hmrc/national-insurance-directors.md explaining the above and sketching what an eventual is_company_director input would do, plus refs (SSCBA 1992 s.8, SI 2001/1004 reg.8, HMRC NIM12000, CA44).
• No code or parameter changes; the conclusion is functionally correct for the expected (annual income) interface and no short-term action is required.

Test plan

• Markdown lints cleanly (links, admonition).
• Docs build job picks up the new page under programs/gov/hmrc/.

🤖 Generated with Claude Code