# FILE: config/coverage.yaml version: "1.0" jurisdiction: "UK" tax_year: "2024-25" tax_year_boundary: start: "2024-04-06" end: "2025-04-05" defaults: confidence_thresholds: ocr: 0.82 extract: 0.85 date_tolerance_days: 30 require_lineage_bbox: true allow_bank_substantiation: true # when primary statement missing, allow verified bank YTD + reconciliation document_kinds: # canonical kinds used by extractor/classifier (map your classifier labels to these) - P60 - P45 - P11D - PayslipMonthly - FinalPayslipYTD - EmploymentContract - AccountsPAndL - AccountsBalanceSheet - CapitalAllowancesSchedule - MileageLog - LettingAgentStatements - TenancyLedger - MortgageInterestCertificate - OwnershipShareProof - OccupancyLog - BookingsCalendar - BankStatements - BuildingSocietyInterestCert - BankInterestAnnualStatement - DividendVouchers - ConsolidatedTaxVoucher - SLCAnnualStatement - PensionContributionStatement - GiftAidStatement - ForeignIncomeStatement - OverseasTaxCreditStatement - TrustDistributionStatement - EstateR185 - CGT_BrokerAnnualReport - CGT_Computation - RemittanceBasisWorkpaper - ResidenceEvidence - HMRC_CodingNotice - HMRC_PaymentOnAccount - OtherSupportingDoc guidance_refs: # Handy lookup keys used by AskClarifyingQuestion; keep them high-level & stable SA100_Notes_2025: { doc_id: "SA150-Notes-2025", kind: "Notes" } SA102_Notes_2025: { doc_id: "SA102-Notes-2025", kind: "Notes" } SA103S_Notes_2025: { doc_id: "SA103S-Notes-2025", kind: "Notes" } SA103F_Notes_2025: { doc_id: "SA103F-Notes-2025", kind: "Notes" } SA105_Notes_2025: { doc_id: "SA105-Notes-2025", kind: "Notes" } SA106_Notes_2025: { doc_id: "SA106-Notes-2025", kind: "Notes" } SA107_Notes_2025: { doc_id: "SA107-Notes-2025", kind: "Notes" } SA108_Notes_2025: { doc_id: "SA108-Notes-2025", kind: "Notes" } SA109_Notes_2025: { doc_id: "SA109-Notes-2025", kind: "Notes" } SA110_Notes_2025: { doc_id: "SA110-Notes-2025", kind: "Notes" } triggers: # Evaluate against KG & intake flags to decide which schedules apply SA102: any_of: - exists: IncomeItem[type="Employment"] - taxpayer_flag: has_employment SA103S: any_of: - exists: IncomeItem[type="SelfEmployment" AND turnover_lt_vat_threshold=true] - taxpayer_flag: is_self_employed_short SA103F: any_of: - exists: IncomeItem[type="SelfEmployment" AND turnover_ge_vat_threshold=true] - taxpayer_flag: is_self_employed_full SA105: any_of: - exists: IncomeItem[type="UKPropertyRent"] - taxpayer_flag: has_property_income SA106: any_of: - exists: IncomeItem[type IN ["ForeignInterest","ForeignDividends","ForeignEmployment","EEA_FHL","OverseasProperty"]] - taxpayer_flag: has_foreign_income SA107: any_of: - exists: TrustDistribution - exists: EstateIncome - taxpayer_flag: has_trust_or_estate_income SA108: any_of: - exists: CapitalGain - taxpayer_flag: has_disposals SA109: any_of: - taxpayer_flag: claims_remittance_basis - exists: NonUKResident SA110: any_of: - filing_mode: paper - taxpayer_flag: wants_manual_calculation schedules: SA102: # Employment guidance_hint: SA102_Notes_2025 evidence: - id: P60 role: REQUIRED boxes: ["SA102_b1", "SA102_b2"] # pay and UK tax taken off acceptable_alternatives: ["P45", "FinalPayslipYTD"] validity: within_tax_year: true reasons: short: "P60 (or P45/final payslip) provides year-to-date pay and PAYE tax figures for boxes 1–2." - id: P11D role: CONDITIONALLY_REQUIRED condition: exists(BenefitInKind=true) boxes: [ "SA102_b9", "SA102_b10", "SA102_b11", "SA102_b12", "SA102_b13", "SA102_b14", "SA102_b15", "SA102_b16", "SA102_b17", "SA102_b18", "SA102_b19", "SA102_b20", ] acceptable_alternatives: ["EmployerStatement"] validity: available_by: "2025-07-06" reasons: short: "P11D carries benefits/expenses that map to boxes 9–20 when not payrolled." - id: SLCAnnualStatement role: OPTIONAL boxes: ["SA102_b21", "SA102_b21_1"] reasons: short: "Student/Postgrad loan indicators and plan types where applicable." - id: PayslipMonthly role: OPTIONAL boxes: ["SA102_b3"] # tips/other payments not on P60 acceptable_alternatives: [] - id: EmploymentContract role: OPTIONAL boxes: [] reasons: short: "Used only for disambiguation (OFF-PAYROLL/IR35, director)." cross_checks: - name: "PAYE Reconcile" logic: "Sum(payrolled_BIKs_excluded_from_SLR) handled; P60 box totals = SA102_b1; PAYE tax = SA102_b2 within ±£1." SA103S: # Self-employment (short) guidance_hint: SA103S_Notes_2025 evidence: - id: AccountsPAndL role: REQUIRED boxes: ["SA103S_b9", "SA103S_b15", "SA103S_b28"] reasons: short: "Turnover and allowable expenses supporting net profit figures." - id: BankStatements role: REQUIRED boxes: ["SA103S_b9", "SA103S_b11", "SA103S_b17"] reasons: short: "Bank corroboration of takings/expenses (cash basis or traditional)." - id: CapitalAllowancesSchedule role: CONDITIONALLY_REQUIRED condition: exists(ExpenseItem[category='CapitalAllowances']) boxes: ["SA103S_b49"] - id: MileageLog role: OPTIONAL boxes: ["SA103S_b20"] - id: HMRC_CodingNotice role: OPTIONAL boxes: [] reasons: short: "Basis period changes or coding interactions." selection_rule: prefer_short_if: "turnover < VAT_threshold AND no_complex_adjustments" else_use: "SA103F" SA103F: # Self-employment (full) guidance_hint: SA103F_Notes_2025 evidence: - id: AccountsPAndL role: REQUIRED boxes: ["SA103F_b15", "SA103F_b31", "SA103F_b73"] - id: AccountsBalanceSheet role: REQUIRED boxes: [] - id: BankStatements role: REQUIRED boxes: ["SA103F_b15", "SA103F_b31"] - id: CapitalAllowancesSchedule role: CONDITIONALLY_REQUIRED condition: exists(ExpenseItem[category='CapitalAllowances']) boxes: ["SA103F_b50", "SA103F_b52", "SA103F_b55", "SA103F_b57"] - id: MileageLog role: OPTIONAL boxes: ["SA103F_b20"] notes: long_form_needed_if: - "turnover >= VAT_threshold" - "claims overlap adjustments, averaging, or multiple trades" SA105: # UK Property (incl. UK FHL) guidance_hint: SA105_Notes_2025 evidence: - id: LettingAgentStatements role: REQUIRED boxes: ["SA105_b5", "SA105_b20", "SA105_b29"] # income and totals; totals vs. sum of expenses acceptable_alternatives: ["TenancyLedger", "BankStatements"] reasons: short: "Gross rents, fees and charges per-year by property/portfolio." - id: MortgageInterestCertificate role: CONDITIONALLY_REQUIRED condition: exists(ExpenseItem[category='FinanceCosts']) boxes: ["SA105_b44"] # feeds SA110 basic-rate credit - id: OwnershipShareProof role: CONDITIONALLY_REQUIRED condition: property_joint_ownership=true boxes: ["SA105_b3"] - id: OccupancyLog role: CONDITIONALLY_REQUIRED condition: candidate_FHL=true boxes: ["SA105_b5", "SA105_b20"] acceptable_alternatives: ["BookingsCalendar"] - id: BankStatements role: OPTIONAL boxes: ["SA105_b20", "SA105_b29"] cross_checks: - name: "Property Income Allowance Gate" logic: "If SA105_b20.1 claimed then no expense boxes 24–29 or FHL expense boxes 6–12 allowed." SA106: # Foreign guidance_hint: SA106_Notes_2025 evidence: - id: ForeignIncomeStatement role: REQUIRED boxes: ["SA106_b1", "SA106_b2", "SA106_b3", "SA106_b5"] reasons: short: "Dividends/interest/overseas employment; gross and tax paid." - id: OverseasTaxCreditStatement role: CONDITIONALLY_REQUIRED condition: claims_FTCR=true boxes: ["SA106_b2", "SA106_b5"] - id: EEA_FHL_OccupancyLog role: CONDITIONALLY_REQUIRED condition: exists(IncomeItem[type='EEA_FHL']) boxes: ["SA106_b14", "SA106_b15"] - id: BankStatements role: OPTIONAL boxes: ["SA106_b1", "SA106_b3"] notes: remittance_interaction: "If remittance basis claimed, mirror to SA109." SA107: # Trusts etc guidance_hint: SA107_Notes_2025 evidence: - id: TrustDistributionStatement role: REQUIRED boxes: ["SA107_b1", "SA107_b2", "SA107_b3"] - id: EstateR185 role: CONDITIONALLY_REQUIRED condition: received_estate_income=true boxes: ["SA107_b9", "SA107_b10"] - id: BankStatements role: OPTIONAL boxes: [] SA108: # Capital Gains guidance_hint: SA108_Notes_2025 evidence: - id: CGT_BrokerAnnualReport role: REQUIRED boxes: [ "SA108_b4", "SA108_b5", "SA108_b6", "SA108_b9", "SA108_b11", "SA108_b14", ] reasons: short: "Disposals, proceeds, allowable costs, gain breakdowns (residential vs other)." - id: CGT_Computation role: REQUIRED boxes: ["SA108_b28", "SA108_b34"] - id: BankStatements role: OPTIONAL boxes: ["SA108_b4", "SA108_b5"] special_2024_25: adjustment_note: "Rate change adjustment for disposals on/after 2024-10-30 may be required." SA109: # Residence / Remittance guidance_hint: SA109_Notes_2025 evidence: - id: ResidenceEvidence role: REQUIRED boxes: ["SA109_b1", "SA109_b7", "SA109_b8", "SA109_b9"] - id: RemittanceBasisWorkpaper role: CONDITIONALLY_REQUIRED condition: claims_remittance_basis=true boxes: ["SA109_b28", "SA109_b39"] - id: ForeignIncomeStatement role: OPTIONAL boxes: ["SA109_b28", "SA109_b39"] SA110: # Tax calculation summary (paper/manual) guidance_hint: SA110_Notes_2025 evidence: - id: HMRC_PaymentOnAccount role: OPTIONAL boxes: ["SA110_b10", "SA110_b11"] - id: HMRC_CodingNotice role: OPTIONAL boxes: ["SA110_b7", "SA110_b8", "SA110_b9"] notes: online_filing: "If online, SA110 is computed automatically; still store calculation lineage for audit." SA100: # Core return - savings/dividends/gift aid, etc. guidance_hint: SA100_Notes_2025 evidence: - id: BankInterestAnnualStatement role: CONDITIONALLY_REQUIRED condition: exists(IncomeItem[type='SavingsInterest']) boxes: ["SA100_b1"] - id: DividendVouchers role: CONDITIONALLY_REQUIRED condition: exists(IncomeItem[type='Dividends']) boxes: ["SA100_b2"] acceptable_alternatives: ["ConsolidatedTaxVoucher"] - id: PensionContributionStatement role: CONDITIONALLY_REQUIRED condition: exists(PensionContribution[relief_method='RAS']) boxes: ["SA100_b4"] - id: GiftAidStatement role: OPTIONAL boxes: ["SA100_b5"] status_classifier: # How we classify found evidence for coverage present_verified: min_ocr: 0.82 min_extract: 0.85 date_in_year: true present_unverified: min_ocr: 0.60 min_extract: 0.70 date_in_year_or_tolerance: true conflicting: conflict_rules: - "Same doc kind, different totals for same period ±£1" - "Totals disagree with KG aggregates by >£1" missing: default: true conflict_resolution: precedence: [ "LettingAgentStatements", "P60", "P11D", "ConsolidatedTaxVoucher", "BankStatements", "ManualEntry", ] escalation: to_review: true reason_templates: - "Document totals disagree with computed aggregates." - "Low confidence OCR; request re-upload or alternative." question_templates: default: text: "To complete the {schedule} for {tax_year}, we need {evidence}. These documents support boxes {boxes}. If you don’t have this, you can provide {alternatives}." why: "{why}. See guidance: {guidance_doc}." reasons: P60: "P60 provides your year-end pay and PAYE tax figures for the employment page." P11D: "P11D lists benefits and expenses that map directly to boxes 9–20 when not payrolled." LettingAgentStatements: "HMRC expects evidence of gross rents and expenses to support SA105 totals." MortgageInterestCertificate: "Mortgage interest supports the basic-rate tax reduction computation." CGT_BrokerAnnualReport: "Brokers’ annual summaries and computations substantiate proceeds, costs and gains." privacy: # Ensure we never index PII into vectors vector_pii_free: true redact_patterns: - NI_Number - UTR - IBAN - SortCode - AccountNumber - Email - Phone