b324ff09ef
Some checks failed
CI/CD Pipeline / Code Quality & Linting (push) Has been cancelled
CI/CD Pipeline / Policy Validation (push) Has been cancelled
CI/CD Pipeline / Test Suite (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-coverage) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-extract) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-firm-connectors) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-forms) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-hmrc) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-ingestion) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-kg) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-normalize-map) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-ocr) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-rag-indexer) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-rag-retriever) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-reason) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (svc-rpa) (push) Has been cancelled
CI/CD Pipeline / Build Docker Images (ui-review) (push) Has been cancelled
CI/CD Pipeline / Security Scanning (svc-coverage) (push) Has been cancelled
CI/CD Pipeline / Security Scanning (svc-extract) (push) Has been cancelled
CI/CD Pipeline / Security Scanning (svc-kg) (push) Has been cancelled
CI/CD Pipeline / Security Scanning (svc-rag-retriever) (push) Has been cancelled
CI/CD Pipeline / Security Scanning (ui-review) (push) Has been cancelled
CI/CD Pipeline / Generate SBOM (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
CI/CD Pipeline / Notifications (push) Has been cancelled
406 lines
13 KiB
YAML
406 lines
13 KiB
YAML
# 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
|