Replace the single-pass, exact-match-only audit with the two-pass model from
imageright_claim_review_audit_methodology.md, applied across all 10 SHAPE
checklist items:
- TaskAudit.status (3-state) -> TaskAuditClassification (7-state): PASS,
PASS_WITH_NAMING_EXCEPTION, MANUAL_REVIEW, FAIL_MISSING, FAIL_LATE,
FAIL_WRONG_ARTIFACT, NOT_APPLICABLE. New columns for confidence score,
evidence bucket, naming-exception/manual-review flags, msg subject/sent
date, attachment filenames, a human-readable evidence summary, and the
full scoring signal trail (matched_signals).
- New audit-scoring.ts: weighted metadata + content scoring per the
methodology's table, generalized to use each spec item's own
keywords/docTypes rather than a hardcoded claim-specific list.
- New content-inspector.ts: downloads and parses `.msg` (subject, sender,
sent date, body, attachments via @kenjiuno/msgreader), `.xlsx` (sheet
names/cell text via xlsx), and `.pdf` (text-layer only via pdf-parse,
no OCR) — recursing one level into email attachments.
- ImageRightClient: new getPageImageContent() using the v2 REST API
(`/api/v2/pages/{pageId}/images/{imageId}/{version}`) — the only endpoint
that returns raw file bytes; v1 only exposes JSON metadata. Verified live
against a real .msg (correct OLE2 signature, exact byte-size match).
- audit-matching.ts: matchesKeywords is now plural/singular-tolerant
(normalizeForMatch) — fixes false negatives like "Open Claims Review" not
matching keyword "CLAIM REVIEW". Added docTypesToExtensions, mapping the
spec's generic doc_types labels to real file extensions (evidence shows
these labels describe file format, not ImageRight's document-type
taxonomy).
- audit-engine.ts: auditSpecItem() replaces findBestMatch() — scores every
in-window candidate, falls back to strict exact-match (fast path, no
content download) when possible, otherwise deep-inspects the top
candidate and only confirms PASS_WITH_NAMING_EXCEPTION when content
positively confirms (not merely "score didn't decrease"). Also fixes a
real accuracy bug: unscoped whole-file document search silently truncates
at ~1000 docs on high-volume accounts (verified live) — ALL_TIME spec
items now iterate every folder instead (findDocumentsSafe).
- UI/API updated for the new classification taxonomy and evidence fields.
Verified end-to-end live against the methodology doc's own worked example
(American Marine Express, Inc., IR document 12884779): real API calls, real
.msg download/parse (found both a signature image and the actual Excel
attachment), correctly classified PASS_WITH_NAMING_EXCEPTION.
68 new/updated tests covering scoring, content parsing (real xlsx bytes;
mocked msgreader/pdf-parse), fuzzy keyword matching, and all 6+1
classification outcomes via auditSpecItem with a fake ImageRight client.
Known follow-up (not resolved here): this client's stored Client.renewalDate
(2026-10-07) and PolicyGroup renewal date (2027-03-02) don't match the
2026-04-04 renewal date used in the methodology doc's own example — worth
reconciling separately, since it determines which target-date windows the
live app actually computes for this client.
