# 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
