MeritFlow

Context Shield

AI-powered, context-aware redaction that detects indirect identifiers (institutions, locations, titles, cohort names, social handles) across text, PDFs, and images. Cuts residual bias by masking identity clues that slip past simple name/email rules while preserving readability for reviewers.

Requirements

Indirect Identifier Detection Engine

"As a program manager, I want the system to automatically detect and flag indirect identifiers so that reviewer bias is reduced beyond simple name and email redactions."

Description

Implements an AI-driven entity and context detection pipeline that identifies indirect identifiers such as institutions, locations, job titles, cohort names, social handles, and distinctive projects across free text, PDFs, and images. Combines named-entity recognition, pattern matching, domain lexicons, and context scoring to minimize residual bias while reducing false positives. Supports multilingual content and configurable confidence thresholds per program. Outputs category-labeled spans with risk scores for downstream redaction. Integrates with MeritFlow’s submission intake to auto-scan on upload and re-scan on edits, and exposes a service API for the review workflow and audit modules.

Acceptance Criteria

Auto-Scan on Upload and Re-Scan on Edit

Given a new submission with text, PDF, and image files is uploaded to MeritFlow When the upload completes Then the detection engine starts within 5 seconds and sets scan status to "Scanning" Given the submission described above When scanning completes for files totaling up to 25 MB Then results are stored and linked to the submission with status "Scanned" within 60 seconds Given the submission has existing scan results When an applicant updates any content or replaces a file Then a new scan is triggered within 5 seconds and previous results are superseded with a new version Given no content changes occur within a 30-second window When multiple edits are saved rapidly Then only one scan is performed (debounced)

Cross-Format Detection Coverage

Given a test fixture contains at least 20 known indirect identifiers across plain text, PDFs (embedded and scanned), and images When scanned at a 0.80 confidence threshold Then ≥95% of seeded identifiers are returned as spans labeled with one of {institution, location, job_title, cohort_name, social_handle, project_name} and each span includes a risk score in [0,1] Given detections reference PDFs When results are returned Then each span includes page number and either character offsets or bounding box coordinates Given detections reference images When results are returned Then each span includes bounding boxes in pixel coordinates relative to the source image Given detections reference plain text When results are returned Then each span includes start and end character offsets

Per-Program Confidence Thresholds

Given Program A has a detection threshold of 0.70 and Program B has 0.90 configured When both programs scan the same content Then spans with scores in [0.70, 0.89] appear only for Program A Given a program updates its threshold value When a subsequent scan runs Then the new threshold is applied and stored with the scan metadata Given a program has no custom threshold When scanning occurs Then the system default threshold is used and recorded in results

Multilingual Detection Capability

Given labeled corpora for English, Spanish, and French indirect identifiers When batch scanning at each program's configured threshold Then macro F1 ≥ 0.85 for English and ≥ 0.80 for Spanish and French on the corpora Given a mixed-language submission is scanned When language auto-detection runs Then the primary language is identified per document section and applied to the detection pipeline Given content is in an unsupported language When scanned Then the API includes a warning flag "language_unsupported" and proceeds with best-effort fallback

False Positive Control via Context Scoring

Given a negative-control corpus with no indirect identifiers and at least 50 ambiguous terms When scanned at a 0.80 threshold Then the false positive rate is ≤ 3% by span count and ≤ 1 false positive per 5 pages on PDFs Given ambiguous mentions lacking identity context (e.g., generic job nouns without possessive association) When scanned Then they are not returned as detections Given identity-bearing context (e.g., "As Director of Oncology at Mercy Hospital") When scanned Then the mention is detected with an appropriate category label and a score ≥ threshold

Service API Contract and Performance

Given an authenticated POST to /v1/context-shield/detect with content ≤ 2 MB When processed Then the response is 200 within 800 ms p95 and includes: spans[], category, score, offsets/boxes, source_type, source_id, language, model_version, threshold_used, scan_id Given invalid input (missing content or malformed) When requested Then the API returns 400 with an error code and message; for payloads > 25 MB returns 413; for unauthorized access returns 401/403 Given an Idempotency-Key header is provided with a repeat request within 24 hours When the same payload is posted Then the same scan_id and results are returned Given rate limits are exceeded When subsequent requests are made Then 429 is returned with standard rate-limit headers

Auditability and Traceability of Scans

Given any scan is executed When results are persisted Then an audit record is written containing submission_id, program_id, scan_id, model_version, language, threshold_used, started_at, completed_at, actor, and result summary counts Given multiple scans exist for a submission When the audit module requests history Then it can retrieve ordered versions and a diff of spans between versions Given a reviewer inspects a detected span When justification is requested Then the system returns the contributing component (e.g., lexicon/pattern/rule id or model tag) associated with the score

Multi-Modal Ingestion & OCR

"As an operations lead, I want reliable OCR for PDFs and images so that all submission formats receive the same level of redaction coverage."

Description

Adds robust text extraction for PDFs and images using OCR with layout retention and language auto-detection to normalize content for redaction. Handles embedded fonts, scanned documents, and images within PDFs; captures bounding boxes for each token to enable precise masking later. Supports bulk processing queues, retry logic, and checksum de-duplication to control costs and latency. Integrates with existing file storage and submission processing so all uploaded artifacts are extractable and analyzable by Context Shield.

Acceptance Criteria

OCR Extraction with Layout Retention for Mixed-Content PDFs

Given a multi-page PDF containing native text, embedded images, tables, headers/footers, and footnotes When the file is processed by the ingestion service Then extracted text preserves reading order at the block level (headings, paragraphs, lists) across all pages And tables are detected and represented with row/column structure with ≥95% cell-detection F1 on the reference test set And text present inside embedded images is OCR’d and merged into the correct page positions And each emitted token includes page number, bounding box (x, y, width, height) in pixels, line ID, and paragraph ID And processing completes within 10 seconds for a representative 10-page PDF under standard queue load

Language Auto-Detection and Multilingual OCR for Scanned Images

Given a batch of 100 scanned image files (TIFF/JPEG/PNG) containing English, Spanish, and Arabic pages When the batch is processed Then the primary language is auto-detected per page with ≥95% accuracy against labeled ground truth And OCR output is Unicode with correct script for each page and preserves right-to-left order for Arabic And mixed-language lines are tokenized with a language tag per token And average processing time is ≤2 seconds per page for the batch on standard queue load And the character error rate per page is ≤5% on the multilingual test set

Robust Handling of Embedded Fonts and Unicode in PDFs

Given PDFs that use embedded subset fonts, ligatures (e.g., fi, fl), and non-ASCII characters (e.g., é, —, 漢字, emoji) When the files are processed Then extracted text contains no replacement characters (�) And ligatures are expanded to their constituent characters while preserving visual order And text is normalized to NFC without data loss And the character error rate is ≤1% against ground-truth for these PDFs And token bounding boxes align to the correct glyph positions within ±2px at 300 DPI

Bulk Processing Queue with Retry, Backoff, and Idempotency

Given 5,000 files are enqueued concurrently for ingestion When the worker pool processes the queue Then throughput is ≥50 files per minute sustained for at least 15 minutes under standard resources And processing honors FIFO within priority tiers (higher priority ahead of standard, FIFO within each tier) And transient failures (timeouts, 5xx) are retried up to 3 attempts with exponential backoff starting at 1s And permanent failures (4xx, corrupt file) are not retried and are routed to a dead-letter queue with reason codes And retries are idempotent using a stable deduplication key so no file is extracted more than once And metrics are emitted for successes, retries, failures, and DLQ counts per minute

Checksum-Based De-duplication to Control Costs

Given a user uploads identical files across different submissions When ingestion computes a SHA-256 checksum for each file Then if a completed extraction exists for the checksum, the system reuses existing artifacts and skips reprocessing And duplicates are logged with references to original submission and artifact IDs And de-duplication reduces reprocessing by ≥90% on a synthetic workload with 50% duplicates And reused artifacts are bit-for-bit identical to the originals for text, tokens, bounding boxes, and language tags

Token-Level Bounding Boxes for Precise Masking

Given any processed page When tokens are emitted to the analysis store Then 100% of tokens include bounding boxes with coordinates in page space plus DPI metadata And all bounding boxes lie within page bounds and do not overlap adjacent tokens on the same line by more than 2px And tokens are grouped into lines and paragraphs with consistent reading order And downstream redaction using these coordinates overlays masks with ≤2px misalignment at 300 DPI in UI verification

Seamless Integration with Storage and Submission Pipeline

Given a new submission with files stored in the existing storage service When ingestion starts Then files are read via time-limited signed URLs without persisting file contents to local disk And extracted artifacts (normalized text, tokens, bounding boxes, language tags) are written to the analysis store linked by submission and file IDs And submission processing status transitions through Pending → In-Progress → Completed or Failed with timestamps And user-facing API and UI receive actionable error messages for failures with correlation IDs And downstream Context Shield redaction is automatically triggered when status becomes Completed

Layout-Preserving Redaction

"As a reviewer, I want redactions that keep documents readable and structured so that I can evaluate merit without distraction or data loss."

Description

Performs masking that preserves readability and document structure across modalities. In text, replaces detected spans with category placeholders (e.g., [Institution]) while keeping grammar and word/line counts stable for rubric alignment. In PDFs, applies vector redaction or shape overlays bound to token coordinates, maintaining pagination, headings, and tables. In images, applies blur/box masks tied to OCR bounding boxes. Ensures masked output is irreversible for reviewer roles and exports clean copies for reviewer portals and downloads.

Acceptance Criteria

Text Placeholder Redaction Maintains Layout and Grammar

Given a plain-text application containing indirect identifiers across sentences and paragraphs and layout-preserving mode is enabled When Context Shield redacts the text Then each detected span is replaced with a single bracketed category placeholder from the approved set [Institution|Location|Title|Cohort|Handle|Other] And the total number of lines is unchanged And paragraph breaks and sentence punctuation are preserved And no double spaces, dangling punctuation, or broken words are introduced And the total word count delta is <= 1% compared to the original

PDF Redaction Removes Underlying Content and Preserves Structure

Given a multipage PDF with headings, tables, and body text When Context Shield applies redaction Then redacted content is removed from the PDF content streams (not merely obscured) and is not retrievable via copy/paste or object extraction And page count and page order remain unchanged And table row/column counts remain unchanged And headers/footers render unaltered And searching the PDF for original redacted strings returns zero results

Image Redaction Blurs/Boxes Using OCR Bounding Boxes

Given an image (PNG/JPG) containing text with indirect identifiers and OCR is enabled When Context Shield applies redaction Then each detected identifier region is masked with a box or blur that fully covers its OCR bounding box with at least a 2 px margin And non-identifier regions remain unmodified outside the mask And the output image dimensions and DPI are unchanged And running OCR on the redacted image yields zero matches of the original redacted strings

Role-Based Irreversibility for Reviewers

Given a user with the Reviewer role views a redacted artifact in the portal When they attempt to reveal, copy, download, or inspect the redacted areas Then the original content is not recoverable via UI, API, copy/paste, or DOM inspection And downloads contain only redacted content (no hidden layers or embedded originals) And audit logs record all access and download attempts of redacted artifacts

Reviewer Portal and Download Exports Are Clean and Flattened

Given a reviewer downloads a redacted artifact (text, PDF, image) from the portal When the file is opened in standard viewers Then masked areas remain masked and cannot be made visible by toggling layers or extracting objects And text exports include placeholders in place of redacted spans And PDFs are saved with redaction flattening applied and do not contain the original content in any XObject or stream And images are flattened and contain no hidden layers or metadata revealing originals

Token-Coordinate Binding Guarantees Stable PDF Overlays

Given a PDF with redaction overlays bound to token coordinates When the PDF is viewed at 50%, 100%, and 200% zoom in Acrobat Reader and Chrome PDF viewer and is printed to PDF Then the overlay-to-token alignment error is <= 1 px at each zoom level And overlays remain aligned after font substitution or rasterization during print-to-PDF And no redacted token is left partially visible at any zoom level

Search/Copy Operations Do Not Reveal Masked Data

Given redacted outputs across text, PDF, and image modalities When performing copy/paste from masked regions or full-document text extraction Then masked regions yield placeholders (text) or empty strings (PDF/image) only And performing document-wide search for the original redacted strings returns zero results And running OCR or text extraction on redacted PDFs and images yields no occurrences of the original redacted strings

Configurable Policies & Exceptions

"As a program administrator, I want to configure redaction categories, thresholds, and exceptions so that masking aligns with our program’s fairness guidelines and tolerance for risk."

Description

Provides program-level policy configuration for what to detect and how aggressively to mask, including category toggles, confidence thresholds, and risk profiles. Supports allow/deny lists, whitelisting of domain-specific terms (e.g., methodology names or public initiatives), and custom patterns (e.g., cohort naming schemes). Allows sandbox testing of policies on sample submissions before activation and versioned policy rollouts with rollback. Integrates with admin settings and applies policies automatically during submission processing and re-processing.

Acceptance Criteria

Program Policy: Category Toggles Control Masking Scope

Given a program where detection categories [Institutions, Locations, Titles, Cohort Names, Social Handles] have Institutions and Social Handles set to ON and others set to OFF And an applicant submission contains examples of each category across text, PDF, and image attachments When the submission is processed Then only Institutions and Social Handles are masked across all file types And no instances of Locations, Titles, or Cohort Names are masked And a processing log lists counts per category masked and skipped

Confidence Thresholds and Risk Profiles Enforcement

Given per-category confidence thresholds are set (Institutions=0.85, Titles=0.60) and Risk Profile "Balanced" is selected And detector outputs include confidence scores for each detected token When a submission containing Institution and Title mentions is processed Then any Institution mention with confidence >= 0.85 is masked and < 0.85 is not And any Title mention with confidence >= 0.60 is masked and < 0.60 is not And changing the Risk Profile to "Aggressive" applies the profile’s default thresholds And any manually overridden per-category thresholds remain effective over the profile defaults And an audit entry records the threshold values used at processing time

Allow/Deny Lists and Whitelist Precedence Rules

Given an Allow List contains ["randomized controlled trial", "Open Science Initiative"] And a Deny List contains ["Acme University"] And the detectors also identify "Open Science Initiative" as an Organization When a submission that mentions all three phrases is processed Then "Acme University" is always masked regardless of detector confidence And "randomized controlled trial" and "Open Science Initiative" are never masked even if detected by category rules And if a term exists on both Allow and Deny lists, Deny takes precedence and the term is masked And each masking decision records whether it was caused by Allow, Deny, or detector threshold logic

Custom Pattern Detection for Cohort Naming Schemes

Given an admin defines a custom pattern named "CohortCode" with regex [A-Z]{2}[0-9]{2}-Cohort-[0-9]{4} And the category "Cohort Names" is enabled for masking When submissions containing strings that do and do not match the pattern are processed Then all strings matching the pattern are masked as Cohort Names And non-matching strings are not masked by this rule And disabling the custom pattern prevents further masking by it without impacting other categories

Sandbox Test of Policies Prior to Activation

Given a draft Policy v2 with modified toggles, thresholds, lists, and patterns And a sandbox set of N sample submissions is selected When the admin runs a sandbox test Then a side-by-side preview shows masked versus original for each sample without altering production submissions And a summary displays counts by category, by rule source (detector/allow/deny/pattern), and total masked tokens per submission And no production processing uses v2 until the admin explicitly activates it

Policy Versioning, Activation, and Rollback

Given Policy v1 is active and Policy v2 is created as a new version with changes When v2 is activated Then all new submissions are processed with v2 And previously processed submissions retain v1 results until explicitly reprocessed And when the admin rolls back to v1, new submissions use v1 and any selected items reprocessed are re-masked under v1 And the version history records creator, timestamps, change summary, activation, rollback, and the user performing each action

Automatic Application During Processing and Re-processing

Given a program has an active policy version in Admin Settings When a new submission is received via portal or API Then the active policy is applied automatically during ingestion across text, PDFs, and images And when an admin triggers re-processing of an existing submission, the current active policy version is applied And processing status, policy version used, and redaction results are persisted and visible in Admin Settings with timestamps

Reviewer-Safe Workflow Integration

"As a grant coordinator, I want reviewers to receive only masked versions while internal checks still use originals so that reviews remain blind without disrupting operations."

Description

Delivers redacted artifacts to reviewers by default while retaining originals for authorized staff and automated services. Automatically routes masked versions to the blind review stage, ensures notifications and links in the reviewer portal point to redacted files, and prevents copy/paste leakage where applicable. Allows conflict-of-interest checks and eligibility automation to run on originals in the background. Provides fallbacks if redaction fails (e.g., hold for admin approval) and clearly surfaces redaction status in the review UI and API.

Acceptance Criteria

Default Redacted Delivery in Blind Review Stage

Given an application with uploaded artifacts (text, PDF, image) and redaction completed When the application transitions to Blind Review stage Then only the redacted versions are attached to the review packets assigned to reviewers And originals are excluded from reviewer-visible bundles And the transition event logs the artifact IDs with version=redacted in the audit trail Given an application without artifacts When it enters Blind Review stage Then no artifact links are shown to reviewers

Reviewer Portal Links Serve Redacted Artifacts

Given a signed-in reviewer with an assigned application When they open any artifact link in the reviewer portal or notification Then the URL resolves to a redacted file (version=redacted) verified by asset metadata redaction_status=redacted And the filename includes a -redacted suffix And the response header X-Artifact-Version=redacted is present Given an attempt to alter a link to request version=original When the reviewer issues the request Then the API returns 403 Forbidden and transmits 0 bytes of the original

Copy/Paste Leakage Prevention for Reviewers

Given a reviewer viewing redacted text in the in-portal viewer When they select and copy text Then the clipboard contains masked tokens for redacted spans (e.g., [masked]) and never reveals original strings Given a reviewer viewing redacted PDFs When text extraction is attempted via copy or download Then redactions are burned-in or overlaid such that OCR yields masked tokens for redacted spans and original text is unrecoverable Given image artifacts When viewed or downloaded by reviewers Then sensitive regions are obfuscated (pixelated/boxed) and cannot be reversed using standard editors Given artifact download options When a reviewer downloads artifacts Then only redacted versions are available and original download actions are hidden or disabled

Originals Accessible to Authorized Staff and Services

Given a user with role Program Admin or Redaction Officer When accessing an application's artifacts from the staff portal Then both original and redacted versions are available with clear labels And access is logged with user ID, timestamp, IP, and version retrieved Given a user with role Reviewer When accessing the same resources Then original version endpoints are not listed and direct requests return 403 Forbidden Given API access with a server-to-server service token When requesting an artifact with version=original Then the API returns 200 OK with the original And the audit log records client_id and purpose=automation

Background Automation Uses Originals (COI and Eligibility)

Given scheduled COI matching and eligibility rules When the automations run Then they execute against original unredacted data and documents And each rule evaluation log includes source=original and rule_id Given a conflict detected on original content When reviewer assignments are generated Then the conflicted reviewer is blocked from assignment and a COI_BLOCKED error is emitted Given eligibility fails on original data When routing is attempted to Blind Review Then the application is prevented from entering and flagged for staff review with reason code ELIGIBILITY_FAIL

Redaction Failure Fallback and Admin Hold

Given an artifact fails automated redaction or has confidence below 0.85 When the application is about to enter Blind Review Then routing is halted, the application status is set to Redaction Hold, and an admin notification is sent within 2 minutes Given an item on Redaction Hold When an admin approves or manually edits redaction Then the system resumes routing and the application proceeds to Blind Review with updated redacted artifacts Given redaction fails and the admin rejects proceeding When the decision is saved Then reviewer assignment is blocked until override with mandatory justification is recorded in the audit log

Redaction Status Visible in UI and API

Given a reviewer opens an application in the reviewer UI When artifacts are listed Then each artifact displays a Redaction Status badge with values Redacted, Pending, or Held and tooltips are present And artifacts with status Pending are not accessible to reviewers Given a client requests review packets via API When the response is returned Then each artifact object includes fields redaction_status (enum: redacted, pending, failed, held, exempt), redaction_confidence (0.00-1.00), and version (redacted|original) And values are consistent with stored metadata Given a program admin views the staff UI When inspecting an artifact Then both versions show checksum and last_redacted_at timestamp and the action log shows the approver identity

Redaction QA & Feedback Loop

"As a program manager, I want to quickly review and correct redactions so that we continuously improve accuracy without slowing down the review cycle."

Description

Adds an interactive preview for admins to inspect detected spans, adjust masking, and submit corrections that feed back into model tuning and allow/deny lists. Supports bulk approve/override, per-span reason codes, and confidence heatmaps to quickly spot over- or under-redaction. Captures reviewer flags during evaluation and routes them to admins for triage. Aggregates precision/recall metrics by program and category to guide continuous improvement and policy refinement.

Acceptance Criteria

Admin previews detected redactions with confidence heatmap

Given an admin opens the Redaction QA preview for a submission containing text, PDF, and image files When the preview loads Then all detected spans are masked and visually highlighted across all file types And a confidence heatmap legend (0–30, 31–60, 61–85, 86–100) is displayed And each span is color-coded to its confidence bucket and shows confidence value on hover And the total span count and per file-type counts are shown And for text/PDF, masks use the standard token "▇▇▇" preserving line breaks; for images, a blurred bounding box is applied And preview load completes within 2 seconds for submissions up to 100 pages total

Per-span manual override and reason code submission

Given an admin selects a detected span in preview When they click Approve Mask or Unmask Then the span state updates immediately in the UI without full reload And a required reason code must be selected from a configurable list before saving And the system records an audit entry with user, timestamp, action, prior state, model label, model confidence, and reason code And the override persists on refresh and is applied to the submission’s reviewer view

Bulk approve or override across filtered spans

Given an admin filters spans by confidence, type, file, or model reason And selects 1–500 spans When they apply a bulk Approve Mask or Unmask with a shared reason code Then exactly the selected spans update And the operation completes within 5 seconds for up to 500 spans And failures, if any, are reported with span IDs and reasons, without halting other updates And the admin can undo the bulk operation within 10 minutes

Allow/Deny list updates from admin corrections

Given an admin selects a span’s text token(s) in preview When they choose Add to Allow List or Add to Deny List and confirm scope (Program or Global) Then the normalized token/pattern is added to the selected scope with the chosen reason code And a re-scan of the current submission reflects the change within 60 seconds And future scans for the scoped programs apply the updated list And duplicate entries are de-duplicated; conflicts prompt the admin to resolve before saving And an audit entry is recorded

Reviewer flag capture during evaluation

Given a reviewer is viewing a redacted submission in the reviewer portal When they select Flag identity clue or Flag over-redaction on a specific location Then a flag is created with file, page, coordinates or character range, span snapshot, and optional note And the reviewer never sees unmasked original content while flagging And the flag posts within 1 second and is non-blocking to scoring And the reviewer can withdraw or edit the flag before submission of the review

Triage workflow routing reviewer flags to admins

Given one or more reviewer flags exist for a submission When an admin opens the Redaction Triage queue Then flags are listed with severity, type, reviewer, and direct links to the exact location in preview And the admin can Accept as correction, Reject, or Convert to policy (Allow/Deny) with required reason codes And accepted corrections update the submission immediately and notify the original reviewer within 24 hours And queue items transition through statuses (New, In Review, Resolved) and are filterable by program and date

Metrics dashboard aggregates precision/recall by program and category

Given there are human-labeled outcomes from admin overrides and reviewer flags over a selectable date range When an admin opens the Redaction Metrics dashboard Then precision, recall, and F1 are displayed by program and redaction category (e.g., institution, location, title, cohort, handle) And metrics are stratified by confidence buckets and file type (text, PDF, image) And clicking any metric reveals the underlying sample with 95% Wilson CI and sample size And the admin can export the metrics and sample to CSV And dashboard updates reflect new labels within 24 hours

Audit Trail & Access Controls

"As a compliance officer, I want complete auditing and controlled access to originals so that we meet institutional policies and external regulatory requirements."

Description

Maintains a tamper-evident audit log of detections, policy versions, overrides, and user actions. Stores original and redacted versions with secure, role-based access; supports just-in-time unmask requests with approval workflow and reason capture. Ensures encryption in transit and at rest, applies data retention policies, and exports audit reports for compliance. Integrates with MeritFlow’s RBAC, SSO, and activity logging to provide end-to-end traceability for redaction events.

Acceptance Criteria

Tamper-Evident Audit Log for Redaction Events

- Given a redaction process runs on a submission, When it completes, Then an append-only audit entry is created containing event_id (UUIDv4), event_type, submission_id, file_id, actor_id (or 'system'), policy_id, policy_version, timestamp (UTC ISO 8601 with ms), source_hash (SHA-256), redaction_count, detector_versions, and trace_id linking to MeritFlow activity log. - Given an audit log with N entries, When integrity verification runs, Then hash chaining (prev_hash, entry_hash) validates 100% of entries and any tampering triggers 'integrity.failed' within 1 second of detection. - Given a filter by date range, event_type, actor_id, or submission_id, When queried, Then results return within 2 seconds for up to 10,000 entries and include total_count.

Role-Based Access to Original vs Redacted Content

- Given a user with role Reviewer, When requesting a file, Then only the redacted version returns 200 and the original returns 403 and an 'access.denied' audit entry is recorded. - Given a user with permission view_originals, When requesting a file, Then both original and redacted are retrievable; each access creates an 'access.granted' audit entry with purpose and scope. - Given an SSO-authenticated session with role claims, When the user accesses any resource, Then RBAC mapping is applied based on claims and the session_id is associated to all audit entries. - Given a pre-signed download link is issued, When 15 minutes elapse or one use occurs (whichever comes first), Then the link expires and subsequent requests return 410 and are logged.

Just-in-Time Unmask Request Workflow

- Given a reviewer cannot view masked content, When submitting an unmask request with scope selection and a reason of at least 10 characters, Then a request is created with status 'pending' and approvers assigned per policy. - Given a pending request, When an approver approves it, Then a time-bound access grant limited to the requested scope is issued to the requester for a TTL not exceeding 24 hours, and an 'unmask.approved' audit entry is recorded. - Given an approved grant, When the TTL expires or an approver revokes it, Then access is immediately removed, subsequent attempts return 403, and an 'unmask.revoked' audit entry is recorded. - Given a request is denied, When the decision is saved, Then the requester is notified, no access is granted, and 'unmask.denied' is recorded with the denial reason.

Policy Versioning and Overrides Traceability

- Given a policy is updated to a new version, When new detections occur, Then audit entries reference the new policy_version while prior entries remain immutable and queryable. - Given a user applies a manual override (additional redact or unmask), When confirming the change, Then a non-empty reason is required and an 'override.applied' audit entry is recorded with before/after pointers and diff. - Given a submission_id and point-in-time T, When reconstructing, Then the system reproduces the redaction outcome as of T using stored original, policy_version, and ordered overrides with 100% fidelity. - Given an override conflicts with current policy, When saved, Then 'policy_deviation=true' is flagged and the item appears in the compliance review queue.

Encryption and Key Management Enforcement

- Given any client-server connection, When established, Then TLS 1.2+ with modern cipher suites is enforced; legacy protocols/ciphers are blocked and logged. - Given data stored for originals, redacted files, and audit logs, Then encryption at rest uses AES-256 (or stronger) with KMS-managed keys that are rotated at least every 90 days and isolated per tenant. - Given backups are generated, When stored and restored, Then they remain encrypted, restores succeed with authorized keys only, and all operations are audited. - Given attempts to access storage outside the application IAM context, When executed, Then access is denied by policy and an 'access.denied' security event is logged.

Data Retention and Legal Hold Application

- Given a retention policy of 365 days on originals, When a file exceeds 365 days without legal hold, Then the original is purged irreversibly and a 'data.purged' audit entry with a deletion receipt and tombstone hash is recorded. - Given a legal hold is applied to a submission, When the purge job runs, Then the affected records are skipped and 'purge.skipped_legal_hold' is logged. - Given a user deletion request is approved, When processing, Then PII in originals, redacted copies, and metadata is deleted or anonymized within 30 days where lawful, with exceptions noted in audit entries. - Given retention policies are updated, When saved, Then effective dates, scope, and prior versions are preserved for audit and applied to subsequent purge cycles.

Audit Report Export and Verification

- Given an admin requests an audit export for a date range and event_types, When executed, Then a CSV and JSON file are generated within 60 seconds for up to 100,000 events and include total_count and page markers. - Given an export is generated, Then it includes a SHA-256 checksum and an HMAC signature; verification of the download matches the provided values. - Given a non-admin requests an audit export, When attempted, Then the request is denied with 403 and an 'access.denied' audit entry is recorded. - Given an export is downloaded, When opened, Then metadata includes generator version, filters applied, requester_id, created_at (UTC), and trace_id range to correlate with MeritFlow activity logs.

MetaScrub

Automatic removal of hidden file metadata—EXIF, document authors, track changes, comments, revision history, and embedded thumbnails—before reviewer distribution. Prevents accidental identity leakage and tightens compliance without manual preprocessing.

Requirements

Universal Metadata Scrubbing Engine

"As a program manager, I want hidden metadata automatically removed from submitted files before reviewers see them so that we prevent identity leakage and uphold blind review policies."

Description

Implements automatic detection and removal of hidden metadata (EXIF, IPTC, XMP, PDF properties, Office core/custom properties, comments, tracked changes, revision history, embedded thumbnails) across common file types (PDF, DOCX/XLSX/PPTX, ODT, JPG/PNG/TIFF). Runs on every applicant upload and any subsequent file replacement, producing a sanitized derivative stored separately from the original. Integrates into MeritFlow’s submission pipeline so that only sanitized files are routed to reviewer packets and exports. Ensures fidelity of visible content while eliminating identifiers, enabling compliant blind review without manual preprocessing and reducing coordinator workload.

Acceptance Criteria

Auto-Scrub on Applicant Upload

Given an applicant uploads a supported file (PDF, DOCX, XLSX, PPTX, ODT, JPG, PNG, TIFF) When the upload completes successfully Then the system generates a sanitized derivative and stores it separately from the original And the sanitized derivative is available within 10 seconds for files <= 50MB and within 60 seconds for files <= 250MB And both original and sanitized files have SHA-256 hashes recorded And a scrub audit log entry is created with timestamp, file type, actions performed, outcome, and any errors And if the file is password-protected, corrupted, or unsupported, scrubbing is skipped, the item is flagged "Sanitization Required," the original is blocked from reviewer routing, and the coordinator is notified

Auto-Scrub on File Replacement

Given an applicant replaces a previously uploaded file with a new version When the replacement upload completes Then the new file is sanitized using the same rules as initial upload And the prior sanitized derivative is superseded, but the original and previous sanitized versions remain in immutable history accessible to coordinators And the latest sanitized derivative is marked current for distribution And an audit log captures the replacement event linking old and new version IDs

Office Documents Scrubbing (DOCX/XLSX/PPTX/ODT)

Given an Office/ODF document containing comments, tracked changes, revision history, embedded thumbnails, and core/custom properties (Author, Company, Manager, LastModifiedBy, etc.) When the document is sanitized Then all tracked changes are accepted, comments are removed, and revision history is cleared And Core, Extended, and Custom properties are cleared (including Author, Company, Manager, LastModifiedBy, Category, Keywords) and "Remove personal information" flags are applied where available And embedded thumbnails and custom XML parts storing document properties are removed And inspection of the package shows docProps core/custom/extended parts are empty or removed, and no docProps/thumbnail files are present And the file opens in Microsoft Office/LibreOffice without repair prompts

Image Files Scrubbing (JPG/PNG/TIFF)

Given a JPEG/PNG/TIFF image containing EXIF, IPTC, XMP, GPS, and embedded thumbnails When the image is sanitized Then all EXIF/IPTC/XMP blocks (including GPS, CameraModel, SerialNumber, Software, Artist, Copyright, and UserComment) are removed And any embedded thumbnail(s) are removed And orientation is preserved by normalizing pixels then clearing the Orientation tag And exiftool -a -G1 -s shows no EXIF/IPTC/XMP fields remaining And image dimensions, bit depth, and color profile are preserved; pixel data is identical for PNG/TIFF and SSIM >= 0.99 for JPEG

PDF Metadata Scrubbing

Given a PDF with populated Info dictionary and XMP metadata When the PDF is sanitized Then Info dictionary fields (Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, Trapped) are cleared And the XMP packet is removed or rewritten to contain no identifying fields And no embedded document-level metadata remains discoverable via pdfinfo or exiftool And page count and object count changes are limited to metadata removal; rendered content at 300 DPI is visually identical (SSIM >= 0.99) to the original

Reviewer and Export Routing Uses Sanitized Files Only

Given a submission has both original and sanitized versions of a file When reviewer packets are generated or files are exported for review Then only the sanitized derivative is included And direct access to the original is blocked for reviewer roles (returns 403) while remaining accessible to coordinators with explicit permission And if sanitization failed or is pending, the file is excluded from reviewer packets and the packet generation job reports the exclusion with a reason

Visible Content Fidelity and Functional Integrity

Given any supported file is sanitized When the sanitized derivative is compared to the expected user-visible output Then for Office/ODF documents the visible content equals the result of "Accept All Changes" with all comments hidden/removed, with identical page count and layout within a 2% pagination tolerance And for images, visual fidelity is preserved (PNG/TIFF pixel-for-pixel identical; JPEG SSIM >= 0.99) with no cropping or rescaling And for PDFs, page render at 300 DPI shows SSIM >= 0.99 and identical page count And all sanitized files pass virus/malware and file integrity checks and open without errors in common viewers/editors

Policy-Based Scrub Rules per Program

"As a compliance officer, I want to tailor which metadata fields are removed or retained per program so that our processes meet institutional and funder requirements."

Description

Provides an admin UI and policy engine to configure scrub behavior at program, round, and file-type levels. Supports presets (e.g., 'Strict Blind', 'Standard Privacy') and granular toggles/allowlists (e.g., preserve DOI and Keywords in PDFs, remove all author and company fields). Policies versioned and auditable, with test mode allowing admins to upload sample files and view what would be removed before activation. Ensures MetaScrub aligns to varying institutional and funder compliance requirements without code changes.

Acceptance Criteria

Program-Level Policy Creation and Application

Given an admin with Manage Policies permission and a program named "STEM Grants 2025" When the admin selects preset "Strict Blind", names the policy "STEM Strict v1", and assigns it at the program level Then policy version 1.0 is created and marked Active for the program And new submissions to any round in the program are auto-scrubbed using policy version 1.0 And previously distributed reviewer files are not altered retroactively And the Program > Compliance settings page displays the active policy name and version

Round-Level Policy Override

Given a program with an Active program-level policy version 1.0 And the program has Round 1 and Round 2 When the admin creates a round-level override for Round 2 using preset "Standard Privacy" and activates it Then Round 2 uses the override policy for all scrubs while Round 1 continues to use the program-level policy And the UI for Round 2 displays an "Override" badge with the policy name and version And reviewer distributions from Round 2 are scrubbed with the override policy rules

Granular File-Type Toggles and Allowlists

Given a policy draft where PDF rules preserve DOI and Keywords and remove Author, Creator, Producer, Subject, Company, XMP dc:creator, and embedded thumbnails And DOCX rules remove document properties Author and Company, remove comments and tracked changes, and preserve custom property "SubmissionID" And JPG/PNG rules remove all EXIF (including GPS coordinates and camera serial) and embedded thumbnails When these toggles are saved in the policy draft Then the policy rule summary displays preserved vs removed fields per file type And processing a representative PDF, DOCX, and JPG in test mode shows preserved fields present and removed fields absent in the output metadata diff

Preset Definitions: Strict Blind and Standard Privacy

Given the system presets "Strict Blind" and "Standard Privacy" exist When an admin views preset details Then "Strict Blind" defaults are: - PDF: remove all author/creator/company/producer fields, clear XMP creator metadata, remove embedded thumbnails, preserve DOI and Keywords - DOCX: remove Author, Company, comments, and tracked changes - Images (JPG/PNG): remove all EXIF including GPS and thumbnails And "Standard Privacy" defaults are: - PDF: remove Author and Company, preserve Subject, Keywords, and DOI - DOCX: remove comments and tracked changes, preserve non-PII document properties except Author and Company - Images (JPG/PNG): remove GPS/location EXIF, preserve non-PII EXIF like orientation And presets are read-only but can be duplicated to create a customizable policy

Policy Versioning and Audit Trail

Given an active policy named "STEM Strict v1" at version 1.0 When an admin edits rules and publishes changes with a change note Then a new immutable version 1.1 is created with timestamp, editor identity, and change note And the audit log captures before/after diffs of rules, the editor's IP, and the scope (program and/or round) And prior versions remain available for rollback and reference but are not editable And the policy history view lists all versions in order with status (Active, Archived)

Test Mode: Upload and Preview Removals

Given an admin opens Test Mode for a policy draft When the admin uploads sample files (PDF, DOCX, JPG/PNG) Then the system performs a dry-run scrub and displays a report showing fields to be removed vs preserved per file type with counts and keys And a banner indicates no changes were applied to stored files and no files were distributed And the admin can download the report as JSON and PDF And the test results are logged in the audit trail with file hashes and timestamps

Enforcement: Block Distribution on Scrub Failure

Given a policy prohibits specific metadata and a file cannot be scrubbed to compliance (e.g., encrypted PDF prevents metadata removal) When the submission reaches reviewer distribution Then the file is not distributed and the system sets status "Scrub Failed" And the admin receives a notification with failure details and remediation options (request replacement, attempt reprocess) And the applicant sees a generic request to re-upload a compliant file without exposing internal policy specifics And upon successful reprocess, distribution proceeds and the audit trail records the retry

Integrity Validation and Safe Preview

"As a reviewer coordinator, I want an automated validation and preview of sanitized files so that I can trust that content is intact and free of identity leaks."

Description

Generates a side-by-side preview and checksum comparison for each sanitized file to confirm that only metadata was altered and that visible content remains unchanged. Flags risky artifacts (e.g., visible author names on cover pages) and offers a reviewer-safe preview link. Stores pre/post cryptographic hashes and basic dimensions to validate integrity. This gives coordinators confidence in the sanitized output and a quick way to spot residual identity indicators before distribution.

Acceptance Criteria

Side-by-Side Preview Renders for Sanitized Files

Given a sanitized file is available, When a coordinator opens its preview, Then the UI displays original (left) and sanitized (right) panes with synchronized page navigation and zoom controls. Given the file is ≤ 25 MB or ≤ 200 pages, When preview is requested, Then the first page renders within 2 seconds and additional pages load progressively. Given the coordinator navigates or zooms, When actions occur in either pane, Then the opposite pane synchronizes to the same page and zoom within 150 ms. Given a rendering error occurs, When the preview fails, Then an actionable error is shown and retry is available; the file receives status "Preview Error" until a successful render.

Pre/Post Hashes and Dimensions Persisted

Given a file is sanitized, When processing completes, Then SHA-256 hashes for original and sanitized binaries are computed and stored with timestamps and the processing run ID. Given integrity details are viewed, When opening the validation record, Then page count, byte size, and for images pixel width/height for pre/post versions are displayed. Given hashes are recomputed, When re-validation is triggered, Then recomputed hashes exactly match stored values; otherwise the system flags "Hash Mismatch" and blocks distribution.

Content Equivalence Validated After Sanitization

Given sanitization completes, When the system performs content comparison, Then extracted text from original and sanitized files is identical after whitespace normalization. Given visual comparison runs, When documents are rasterized at 150 DPI, Then pixel difference ratio between original and sanitized is ≤ 0.1%. Given differences exceed thresholds, When validation fails, Then the file is marked "Content Mismatch", a diff summary (pages affected and difference ratio) is stored, and reviewer distribution is blocked until coordinator acknowledges override.

Residual Identity Indicators Automatically Flagged

Given a sanitized file is produced, When OCR/text extraction runs, Then occurrences of identity indicators (e.g., "Author", "By", email addresses, phone numbers, affiliations, ORCID, personal names from the program stoplist) are detected and stored with page numbers, snippets, and bounding boxes. Given detection confidence ≥ 0.80, When flags are displayed, Then the preview highlights the regions and lists each flag with its reason code and confidence score. Given the coordinator dismisses a flag, When "Dismiss" is confirmed with a note, Then the flag state changes to "Dismissed" and the audit log records user, timestamp, and note. Given no flags are found, When the preview loads, Then a green "No identity indicators found" status badge appears.

Reviewer-Safe Preview Link Enforced

Given a sanitized file passes validation, When a coordinator generates a reviewer link, Then a signed, single-use URL is created that expires after 7 days or after first access, whichever occurs first. Given a reviewer opens the link, When accessing the URL, Then only the sanitized version is streamed; downloads are disabled; response headers omit identifying metadata; attempts to access the original return HTTP 403. Given the link is revoked, When the coordinator selects Revoke, Then subsequent access attempts return HTTP 410 within 60 seconds. Given an unauthenticated or unauthorized user accesses the link, When the request is made, Then the system returns HTTP 403 and no content bytes are served.

Integrity Report and Audit Trail Available

Given validation is complete, When the coordinator exports the integrity report, Then a PDF and JSON report is generated containing pre/post SHA-256 hashes, sizes, page counts, comparison results, and flag summaries. Given the audit log is viewed, When the integrity record is opened, Then actions (sanitize, preview open, link creation, link revoke, flag dismissal, distribution block/override) are listed with user, timestamp, and IP address. Given an external verification, When a hash from the report is recomputed against current stored binaries, Then the values match exactly.

Graceful Handling of Unsupported or Failed Validations

Given an unsupported file type is detected, When sanitization or comparison cannot proceed, Then the system sets status "Validation Unsupported", blocks reviewer distribution by default, and displays remediation guidance to the coordinator. Given hash computation fails, When a transient error occurs, Then the system retries up to 3 times with exponential backoff and logs the failure if unresolved; distribution remains blocked. Given preview generation exceeds 15 seconds for first page, When timeout occurs, Then an error message and Retry option are shown; a background re-render is queued and status updates upon completion.

Chain-of-Custody Audit Logs

"As a compliance auditor, I want exportable logs showing exactly what was removed and when so that I can verify adherence to blind review and privacy policies."

Description

Captures a detailed, immutable log for each processed file, including timestamps, actor (system), original and sanitized file hashes, applied policy version, detected/removed metadata fields, and processing outcome. Exposes per-file and batch export (CSV/JSON) for audits and dispute resolution, and attaches the log to the application record. Supports retention controls aligned to organizational policies. This evidences compliance and simplifies responding to auditor and applicant inquiries.

Acceptance Criteria

Log Creation on File Sanitization

Given a file is submitted for processing by MetaScrub When sanitization completes (Success, Partial, or Failed) Then an audit log entry is created within 2 seconds containing: event_timestamp (ISO 8601 UTC), actor="system", original_file_hash (SHA-256 hex), sanitized_file_hash (SHA-256 hex or null on failure), policy_version, detected_metadata_fields [name,count], removed_metadata_fields [name,count], processing_outcome in {"Success","Partial","Failed"}, processor_version, processing_start, processing_end, duration_ms, application_id, file_id And the entry has a unique immutable ID; any attempt to update or delete it via API returns 409 and is itself audited

Per-File Audit Log Attachment to Application Record

Given a processed file belongs to an application When an authorized user views the application's file details Then the audit log is attached and viewable with key fields and a download of the full JSON log And when an unauthorized user attempts access Then the request is denied with 403 and the access attempt is logged And when the API GET /applications/{appId}/files/{fileId}/audit-log is called by an authorized token Then it returns 200 with the JSON log including all required fields; otherwise returns 403 or 404 as appropriate

Batch Export of Audit Logs for Audit Window

Given a compliance auditor selects a program, date range, and format (CSV or JSON) When they request a batch export Then the system generates an export containing all matching log records with schema: id, application_id, file_id, event_timestamp, actor, original_file_hash, sanitized_file_hash, policy_version, detected_metadata_fields, removed_metadata_fields, processing_outcome, processor_version, processing_start, processing_end, duration_ms And timestamps are in ISO 8601 UTC; CSV includes a header row; JSON is newline-delimited objects And exports support up to 50,000 records per file; larger result sets require pagination and provide continuation tokens And the export is downloadable via a pre-signed URL that expires in 24 hours and includes a SHA-256 checksum for integrity

Retention Policy Enforcement with Legal Hold

Given an organization-wide retention policy (e.g., 5 years) is configured When an audit log reaches its retention expiry and no legal hold applies Then the log is purged within 24 hours and a purge event is recorded in the system audit trail including id, purge_timestamp, and policy_version And when a legal hold is applied to the application or file Then associated logs are excluded from purge until the hold is removed and their status shows "On Hold" in API responses And all retention calculations use UTC; administrators can configure policy per program within allowed bounds; misconfigurations are rejected with validation errors

Tamper-Evident Chain and Signature Verification

Given audit logs are written When a new entry is persisted Then entry_hash = SHA-256(entry_payload) and previous_hash link to the prior entry for that file chain are stored to enable chain verification And each entry is digitally signed with the service key; GET /audit-logs/{id}/verify returns signature_valid=true and chain_valid=true for unaltered data And when any stored entry is altered or missing Then daily background verification flags the chain as invalid, raises an alert event, and exposes chain_valid=false via the verify endpoint

Failure and Partial Processing Outcomes Recorded

Given sanitization encounters errors or unsupported metadata When processing ends Then the audit log outcome is "Partial" or "Failed" accordingly, and includes error_code and error_message (machine-readable and human-readable) And for "Failed" outcomes sanitized_file_hash is null and removed_metadata_fields is empty And for "Partial" outcomes remaining_metadata_fields lists items not removed with reasons And the presence of any outcome other than "Success" sets remediation_required=true in the log

Failure Safeguards and Notifications

"As a program manager, I want failures to block distribution and notify the right parties so that unsanitized files never reach reviewers and issues are resolved quickly."

Description

Implements fail-closed behavior: if scrubbing or validation fails, the file is withheld from reviewer distribution, and stakeholders are alerted. Provides clear error states, automatic retries with backoff, and guidance to applicants on how to resolve issues (e.g., re-export to PDF). Enables admin overrides with justification and records all decisions in the audit log. Prevents unsanitized files from entering reviewer workflows while minimizing submission friction.

Acceptance Criteria

Fail-Closed on Scrub or Validation Error

Given a file is submitted to MetaScrub When the scrubber returns a non-zero error code, validation detects unsanitized metadata, or the service times out after 30 seconds Then the file state is set to "Scrub Failed" and marked unsanitized And the file is withheld from reviewer distribution (not attached to reviewer packets and reviewer download endpoints return 403) And an in-app status badge "Scrub Failed" is displayed to admins and the submitter

Automatic Retries with Exponential Backoff

Given a scrub attempt fails with a retriable condition (network error, 5xx, timeout) When the retry policy executes Then the system performs up to 3 retries with backoff intervals of 1 minute, 5 minutes, and 15 minutes And concurrent retries for the same file are prevented (idempotent lock) And after the final failed attempt the state is set to "Scrub Failed (Final)"

Stakeholder Notifications on Final Failure

Given a file reaches "Scrub Failed (Final)" When the state transition occurs Then program admins and the submitter are notified within 60 seconds via email and in-app notification And the notification contains file name, submission ID, error code, timestamp of last attempt, and a link to resolution guidance And duplicate notifications for the same failure event are suppressed

Applicant Error Messaging and Resolution Guidance

Given a submitter views their submission containing a file in "Scrub Failed" When the submission details page loads Then an inline banner shows a plain-language error summary, error code, and last attempt timestamp And actions "Replace File" and "Retry Scrub" are available And "Retry Scrub" is limited to 2 user-initiated attempts per 24 hours per file And a help link provides step-by-step guidance (e.g., re-export to PDF)

Admin Override with Justification

Given a user with the Program Admin role reviews a file in "Scrub Failed" When the admin selects "Override and Distribute" Then the system requires a free-text justification of at least 20 characters and a risk acknowledgment checkbox And upon confirmation, the file state changes to "Override Approved" And the file becomes eligible for reviewer distribution immediately

Comprehensive Audit Logging of Failures and Overrides

Given any scrub attempt, retry, failure, notification, or override event occurs When the event is processed Then an immutable audit log entry is created within 5 seconds containing: ISO-8601 timestamp, actor (or system), event type, submission ID, file ID, file SHA-256 hash, prior state, new state, error code/message (if any), and notification recipients And audit entries are viewable in the Admin Audit Log screen and exportable as CSV

Block Reviewer Access Until Sanitized or Overridden

Given reviewers access assigned submissions When a submission contains files in states other than "Sanitized" or "Override Approved" Then those files are not included in reviewer packets, file lists, or bulk downloads And API endpoints for reviewer file access deny access (403) for such files And packet generation logs indicate excluded files with counts for admin visibility

Scalable Processing Pipeline and SLAs

"As a platform administrator, I want scrubbing to scale reliably during peak submission periods so that we meet turnaround SLAs without delaying reviewer packets."

Description

Adds an asynchronous, horizontally scalable processing queue for MetaScrub with concurrency controls, job prioritization, and health checks. Provides throughput and latency metrics, alerts, and capacity auto-scaling to meet peak submission windows. Ensures deterministic processing order tied to submission events and updates application records in real time upon completion. Delivers predictable performance and availability aligned with program deadlines.

Acceptance Criteria

Peak Load Auto-Scaling SLA

Given the system starts with 2 active workers and autoscaling enabled with min=2 and max=50 And a synthetic workload generates 1,000 MetaScrub jobs per minute for 30 minutes When the workload begins Then active workers scale up to meet or exceed the arrival rate within 5 minutes And P95 end-to-end processing latency is <= 120 seconds after the first 2 minutes of the load window And the end-to-end error rate remains < 0.5% during the 30-minute window And queue lag (oldest enqueued to start) does not exceed 300 seconds When the workload drops to 50 jobs per minute Then workers scale down to within 20% of steady-state capacity within 10 minutes without interrupting in-flight jobs

Deterministic Processing Order

Rule: Dequeue ordering is by priority (High > Normal > Low), then eventTimestamp (ASC, millisecond precision), then submissionId (ASC, UUID) Given a mixed batch of 1,000 jobs with known priorities and timestamps and a clean queue When the pipeline processes them under normal and peak load profiles in three successive runs with a service restart between runs Then the observed completion order exactly matches the defined comparator in all runs And the ordering stability metric (Kendall tau) equals 1.0 between all pairs of runs Given a job experiences a retry Then its ordering keys (priority, eventTimestamp, submissionId) remain unchanged and it never overtakes any job with a strictly earlier comparator

Priority Fast Lane and No-Starvation

Given High and Normal priority jobs arrive at 300 and 700 jobs per minute respectively for 20 minutes And worker pool size is autoscaled between 2 and 50 When processing begins Then at least 60% of active worker slots are allocated to High priority while a High backlog exists And P95 latency for High priority jobs is <= 60 seconds during the window And P95 latency for Normal priority jobs is <= 180 seconds during the window And Normal priority receives at least 10% of worker slots if a High backlog persists longer than 10 minutes (no starvation)

Concurrency Controls and Backpressure

Given global max concurrency is set to 200 and per-program max concurrency to 50 And 500 jobs are enqueued simultaneously across three programs When processing begins Then no more than 200 jobs run concurrently across all programs and no more than 50 per program And additional jobs are queued without failure until capacity is available And internal 5xx errors due to overload remain < 0.5% and dependency 429/5xx responses remain < 1% during the test Given a dependency error rate exceeds 20% for 60 seconds for a specific program When the circuit breaker evaluates Then intake for that program is paused, jobs are requeued with exponential backoff, and other programs continue unaffected

Real-Time Record Updates and Notifications

Given a submission with two files enters the queue When each file completes MetaScrub successfully Then the application record is updated to status "Scrubbed" for that file within 2 seconds of job completion And an audit entry is persisted with fields {jobId, submissionId, fileId, contentHash, detectedMetadata[], startTime, endTime, durationMs, workerId, attempt} And a webhook and UI event are emitted within 2 seconds with a stable deduplication idempotency key Given a file exhausts max retries Then the record status becomes "Scrub Failed" with lastErrorCode and dlqId, and the failure is visible in the UI within 5 seconds

Metrics, Dashboards, and Alerting

Given the service is running When scraping the metrics endpoint Then the following metrics are exposed with labels {programId, priority, workerPool}: queue_depth, queue_lag_seconds, jobs_enqueued_total, jobs_started_total, jobs_completed_total, jobs_failed_total, processing_latency_seconds_bucket, worker_active, autoscale_events_total, retries_total, dlq_depth And a Grafana dashboard displays these metrics with P50/P95/P99 latency and per-priority throughput And an availability SLO of 99.9% queue intake and a latency SLO of 99.5% jobs completed within 5 minutes are defined and visible Given P95 latency exceeds 120 seconds for 5 consecutive minutes or queue_depth > 10,000 for 10 minutes or dlq_depth > 0 for 15 minutes When alerting evaluates Then a high-severity alert is sent to on-call via Slack and email within 2 minutes and includes runbook links

Resilience: Retries, DLQ, and Idempotency

Rule: Transient errors (timeouts, 5xx, network) are retried up to 5 attempts with exponential backoff (initial 5s, multiplier 2, jitter 20%) capped at 2 minutes; permanent errors (4xx validation) are not retried Given 100 jobs fail transiently on first attempt When processed Then at least 95% succeed by the 5th attempt and no job exceeds the max backoff cap Given the same event (submissionId, fileId, contentHash) is enqueued 10 times due to duplicate events When processed Then the file is scrubbed at most once and exactly one audit entry exists; all duplicate events are acknowledged without side effects Given a job reaches max retries When it fails again Then it is moved to the DLQ with cause, lastErrorCode, and replayAfter; and replaying from DLQ after fixing the issue achieves > 95% success

LogoSweep

Computer-vision redaction of logos, seals, watermarks, and branded insignia in scans, slides, and vector PDFs. Finds partial, faint, and background marks, then masks them consistently to maintain true blind review across visual assets.

Requirements

Multi-Format Asset Ingestion

"As a program manager, I want LogoSweep to accept all common visual asset formats so that applicants don’t have to reformat files and reviewers receive consistently redacted materials."

Description

Support upload and processing of raster images (JPG, PNG, TIFF), scanned PDFs, vector PDFs, and slide decks (PPTX) to enable LogoSweep to operate across all common applicant assets. On ingest, detect file type, extract pages/slides, and normalize assets into an internal processing representation, including vector-to-raster fallback when needed for robust detection. Preserve the original file, generate a redacted derivative, and attach both to the submission record. Integrate with MeritFlow’s submission pipeline to automatically trigger processing on file upload and block reviewer access until redaction is complete. Ensure secure, tenant-isolated storage and checksum verification for file integrity.

Acceptance Criteria

Auto-Detect and Validate Supported File Types

Given an applicant uploads a file to a submission When the upload completes Then the system determines the MIME type using content sniffing, independent of file extension And Then files of types JPG, JPEG, PNG, TIFF, PDF, and PPTX are accepted; all others are rejected with a message listing supported formats And Then encrypted/password-protected PDFs are rejected with a descriptive error and no processing is started And Then the detected MIME type, original extension, uploader, timestamp, and tenant ID are logged for audit

Raster Image Ingestion and Normalization

Given a JPG, PNG, or TIFF is uploaded When ingestion runs Then the image is normalized into the internal raster representation with corrected orientation (using EXIF), flattened transparency against a white background, and sRGB color space And Then the internal raster frame records effective dimensions and DPI; if DPI metadata is missing, a default of 300 DPI is applied And Then the original file is preserved unmodified and its SHA-256 checksum matches the pre-upload checksum And Then a preview is generated for UI display without altering the internal processing frame

PDF Ingestion, Page Extraction, and Rasterization Fallback

Given a PDF (scanned, mixed, or vector) is uploaded When ingestion runs Then each page is extracted in order and rendered to an internal raster frame at a minimum effective 300 DPI (configurable) in sRGB And Then page dimensions and orientation are preserved within ±1% of the original rendered size And Then if vector parsing fails or content cannot be reliably analyzed, full-document rasterization is used as a fallback without blocking ingestion And Then the original PDF is preserved unmodified and its SHA-256 checksum verifies on storage

PPTX Slide Deck Ingestion and Rendering

Given a PPTX is uploaded When ingestion runs Then each slide is rendered to an internal raster frame at a minimum effective 300 DPI relative to slide dimensions, preserving aspect ratio and slide order And Then embedded images, shapes, charts, and SmartArt are included in the render; missing fonts are substituted from a configured list and recorded in metadata And Then notes pages and hidden slides are excluded by default, with slide indices recorded for traceability And Then the original PPTX is preserved unmodified and its SHA-256 checksum verifies on storage

Automatic Processing Trigger and Reviewer Access Control

Given an applicant uploads any supported asset to a submission When storage confirmation succeeds Then LogoSweep processing is automatically queued within 5 seconds and the submission shows a Processing status for the asset And Then reviewers are blocked from accessing the asset until redaction completes, with a clear message indicating processing in progress And Then upon successful completion, a redacted derivative is attached, set as the reviewer-visible default, and the original remains accessible only to authorized roles And Then if processing fails, the asset remains hidden from reviewers, the submission displays an actionable error, and a retry option is available

Secure Tenant-Isolated Storage and Checksum Integrity

Given any uploaded asset and its derivatives are stored When writing to storage Then the objects are placed under a tenant-scoped path/bucket with access controls preventing cross-tenant reads and writes And Then transport uses TLS and data at rest is encrypted (AES-256 or cloud-provider equivalent) And Then a SHA-256 checksum is computed on upload, recorded in metadata, and reverified after write; any mismatch marks ingestion Failed and halts processing And Then stored metadata includes tenant ID, submission ID, uploader ID, MIME type, byte size, checksum, creation time, and links between original and redacted derivatives

Robust Mark Detection Engine

"As a grant coordinator, I want the system to reliably find logos and watermarks in varied documents so that blind review integrity is maintained without manual hunting."

Description

Implement a computer-vision pipeline that detects logos, seals, watermarks, and branded insignia in complex contexts, including partial occlusions, faint/translucent overlays, rotations, and background placements. Combine vector path analysis for PDFs, multi-scale template/features for symbol shapes, OCR for stylized brand text, and image heuristics for watermark patterns. Produce mask regions with confidence scores per page/slide and de-duplicate repeated marks. Provide tunable sensitivity per program to balance false positives/negatives. Run efficiently on CPU/GPU, operate in secure/offline environments, and expose structured outputs to downstream redaction and auditing components.

Acceptance Criteria

Detect faint translucent watermarks in scanned documents

Given a labeled validation set of 300 scanned pages containing faint/translucent watermarks (opacity 10–30%) and 100 pages with no marks When the detection engine runs at 300 DPI with default sensitivity Then watermark region recall >= 0.90 at IoU >= 0.50 and precision >= 0.85 on the marked pages And on no-mark pages, total false-positive area <= 1.0% of page area and <= 1 false region per page And each detected region includes mark_type = "watermark", a polygon with >= 4 points, and confidence ∈ [0,1]

Detect logos and seals under occlusion and rotation

Given a labeled set with logos/seals occluded 20–60%, rotated −180° to 180°, across scales 0.5×–2× When the engine runs with default sensitivity Then detection recall >= 0.88 and precision >= 0.90 for logos and seals at IoU >= 0.50 And confidence scores for the same mark do not degrade by more than 0.10 between 0° and 180° rotations

Identify vector-based logos in PDFs without rasterization loss

Given 100 vector-only PDF pages containing path-based logos/seals and 50 vector-only pages with no marks When the engine performs vector path analysis (no rasterization below 300 DPI equivalence) Then recall >= 0.92 and precision >= 0.95 at IoU >= 0.50 for vector marks And detected mask polygons align to vector outlines within 2 px at 300 DPI equivalence and respect clipping/compound paths

Detect stylized brand text and wordmarks

Given a labeled set of 200 pages/slides containing stylized brand text/wordmarks and 100 negatives When the OCR-based detection module runs with language = English Then recall >= 0.90 and precision >= 0.90 at IoU >= 0.50 for brand_text regions And detections are case-insensitive and robust to curved baselines up to 30° arc And output includes mark_type = "brand_text" and normalized_text for each region

De-duplicate repeated marks within and across pages

Given a 50-slide deck where the same logo appears on 30 slides and repeats 2–3 times per slide, plus other unique marks When the engine runs with default sensitivity Then marks labeled as the same brand in ground truth are grouped under one duplicate_group_id with purity >= 0.98 and completeness >= 0.95 And each region includes duplicate_group_id and occurrence_index, and no group contains marks from different brands

Produce structured outputs for downstream redaction and auditing

Given any processed document When the engine completes Then it emits a JSONL where each record contains: page_index, mark_type ∈ {logo, seal, watermark, brand_text}, polygon (>= 4 points), bbox [x,y,w,h], confidence ∈ [0,1], duplicate_group_id (nullable), source_type ∈ {raster, vector}, detection_time_ms And the JSON validates against schema version "1.0" and is readable by redaction and auditing components without transformation And confidence calibration passes: for bins [0.5–0.6, 0.6–0.7, ..., 0.9–1.0], observed precision differs from bin midpoint by <= 0.10

Tunable sensitivity and offline CPU/GPU performance

Given three sensitivity presets {conservative, default, aggressive} and a held-out benchmark When the engine runs on the benchmark with each preset Then aggressive improves recall by >= +5 percentage points over default while precision drops by <= 5 points; conservative improves precision by >= +5 points over default while recall drops by <= 5 points And on a 200-page, 300 DPI document, average runtime <= 2.5 s/page on 8-core CPU and <= 0.9 s/page on NVIDIA T4-class GPU; peak memory <= 3 GB And the engine makes no outbound network calls and runs fully offline; all temporary files are stored in a specified secure local directory

Consistent Redaction Styling

"As a compliance officer, I want redactions to look consistent and non-reversible so that no applicant identity cues leak during blind review."

Description

Apply uniform, non-reversible masking across all detected marks in a submission, with configurable styles (solid fill, blur, pixelate) and program-level defaults. Ensure masks meet contrast and opacity standards to avoid revealing original shapes, and preserve document readability and layout. For vector PDFs, replace paths with neutral vectors; for raster assets, render masks directly into pixels with no separate removable layer. Propagate the same style across all instances and versions of an asset within a submission to avoid bias cues, and validate final output for accessibility and print fidelity.

Acceptance Criteria

Program-Level Default Style Enforcement Across Submission

Given a program has a default redaction style configured (solid fill, blur, or pixelate) and parameters set (e.g., color, blur radius, pixel size) When a submission containing one or more assets is processed by LogoSweep Then all detected marks across all assets in that submission are masked using the program’s default style and parameters And no per-asset or per-mark style deviates from the program default unless an authorized program-level override is applied prior to processing And the same style identifiers and parameter values are present in the processing report for each masked mark in the submission

Uniform Mask Application in Mixed Asset Types (Vector and Raster)

Given a submission contains both vector PDFs and raster images/slides When LogoSweep applies redaction masks Then the visual appearance of masks (style type and configured parameters) is consistent across all assets in the submission And for solid fill, the RGB/CMYK values match within a delta ≤ 1 per channel across all assets And for blur/pixelate, the effective blur sigma or pixel block size matches the configured values within ±5% across all assets And document layout (page count, text positions, object bounding boxes) remains unchanged outside the masked regions

Non-Reversible Redaction in Raster Assets

Given a raster asset (e.g., PNG, JPEG, TIFF) contains detected marks When redaction is applied Then masks are rendered directly into the pixels with no separate editable/redactable layer And masked pixels contain no remnants of the original content in any color or alpha channel (alpha = 1.0 in masked areas for opaque styles) And the exported file contains no embedded thumbnails or metadata that include the unredacted image And opening the output in common editors shows a single flattened layer with the mask baked-in

Non-Reversible Redaction in Vector PDFs

Given a vector PDF contains detected marks represented by paths, images, or XObjects When redaction is applied Then original mark paths/images are removed from the content streams And they are replaced with neutral vector shapes or rasterized masks per the selected style And no Optional Content Groups, transparency groups, or soft masks retain the original shapes And there is no hidden layer or attachment containing the original unredacted content And the PDF passes a content stream inspection where no object references the original mark resource identifiers

Consistency Across Re-uploads and Versioning

Given an applicant re-uploads an asset or a new version of the same asset within the same submission When LogoSweep reprocesses the updated asset Then the previously applied style type and parameters for that submission are reused automatically for all marks in the new version And all instances of that asset within the submission display the same masking style And no mixture of styles occurs across versions of the same asset within the submission And the processing report links versions and confirms identical style parameters

Accessibility and Print Fidelity Validation

Given redaction has been applied to a document intended for blind review When automated accessibility checks run Then existing PDF tagging and reading order are preserved (no new untagged content outside masks) And color contrast for remaining readable text meets WCAG AA levels as prior to redaction When print simulations are run (grayscale and CMYK) Then mask regions remain uniformly opaque and indistinguishable in tone/texture from one another And no moiré/banding or transparency reveals original shapes in print proofs

Contrast and Opacity Standards for Masking

Given program-level minimums are configured for mask opacity and strength When masks are applied Then solid fill masks use 100% opacity with a uniform fill color; no pixel within the mask has opacity < 1.0 And blur masks use a blur radius ≥ the configured minimum and remove recognizability of underlying shapes to the configured threshold And pixelate masks use a block size ≥ the configured minimum and remove recognizability of underlying shapes to the configured threshold And mask coverage extends at least 2 px (at 300 DPI) beyond detected mark bounds to avoid edge reveal And anti-aliasing does not introduce semi-transparent edges below the configured opacity threshold

Manual Review & Confidence Thresholds

"As a program manager, I want to review and adjust suggested redactions based on confidence so that we balance automation speed with accuracy."

Description

Provide a redaction preview workspace where staff can review detected marks, see confidence scores, and approve, add, or remove masks before assets are released to reviewers. Enable configurable auto-apply thresholds and route low-confidence detections to manual review. Include quick annotation tools, keyboard shortcuts, zoom/pan, batch approve, and per-page acceptance. Integrate with MeritFlow workflow gates so reviewer assignment is blocked until approval. Capture approver identity, timestamps, and notes to support later audits and continuous model tuning.

Acceptance Criteria

Redaction Preview Shows Detections and Confidence

Given an uploaded asset with detected visual marks When a staff member opens the redaction preview workspace Then each detected mark is displayed with a visible mask and its confidence score shown as a percentage with one decimal place And a detections panel displays the total count and allows sorting by confidence ascending or descending And assets with no detections show a "No detections found" state and enable manual mask addition And detections are displayed on the correct page thumbnails for multi-page assets

Auto-Apply Thresholds and Manual Routing

Given program-level thresholds are configured with AutoApplyThreshold = T and ManualReviewFloor = L where 0 ≤ L < T ≤ 1.0 When an asset is processed by LogoSweep Then detections with confidence ≥ T are auto-applied and labeled Auto-Applied And detections with confidence < L are not auto-applied and are labeled Low Confidence and routed to manual review And detections with L ≤ confidence < T are labeled Needs Review and visible in the manual review queue And changing T or L applies to subsequent processing runs and is audited with who, when, and new values

Manual Approve, Add, and Remove Masks

Given a staff member is in the redaction preview workspace When the user approves a detected mask Then the mask status becomes Approved, it is locked from further auto-changes, and its approval is recorded When the user removes a detected mask Then the mask is deleted from the page, its removal is recorded, and the detection is marked as Rejected When the user adds a new mask using annotation tools Then a new Manual mask is created with page reference and geometry visible in the preview and list And saving the asset persists all changes so that reloading the workspace restores the same mask set and statuses

Zoom, Pan, Shortcuts, and Annotation Tools

Given an asset is open in the preview workspace When the user zooms and pans using UI controls or keyboard shortcuts Then the canvas responds smoothly and maintains mask fidelity and alignment at all zoom levels When the user opens the shortcuts help overlay Then a list of shortcuts for Approve, Remove, Add Mask, Next/Prev page, Batch Approve, and Save is displayed And each listed shortcut performs the same action as its corresponding UI control And annotation tools support rectangular and polygon masks across raster images and vector PDFs

Batch Approve and Per-Page Acceptance Controls

Given a multi-page asset with unresolved detections When the user clicks Accept Page on a page Then all unresolved masks on that page are approved and the page is marked Accepted When the user performs Batch Approve with a selected filter (e.g., Auto-Applied, Needs Review) Then only the filtered set is approved and a confirmation shows the count approved And the Approve Asset action remains disabled until all pages are Accepted or all detections are resolved And attempting Approve Asset with unresolved detections shows a blocking message listing remaining items

Workflow Gate Blocks Reviewer Assignment Until Approval

Given LogoSweep redaction is required for a program When an asset’s redaction status is not Approved Then any attempt to assign reviewers via UI is blocked with a message "Redaction approval required" And API attempts to assign reviewers return a 409 Conflict error with code REDACTION_APPROVAL_REQUIRED When the asset’s redaction status becomes Approved Then reviewer assignment via UI and API succeeds and the asset transitions to Review Ready

Audit Trail and Model Tuning Feedback

Given users approve, add, or remove masks or accept pages/assets When any such action is performed Then the system records user identity, timestamp (UTC), action type, affected mask/detection IDs, page, confidence (if applicable), and optional note When an export is requested for a date range and program Then a downloadable CSV and JSON are generated containing manual approvals/removals/additions with derived labels (true positive, false positive, false negative) for model tuning And the audit log is viewable in the UI with filters by action type, user, date, and asset

Metadata & Textual Brand Scrub

"As a grants administrator, I want metadata and brand text removed along with visual marks so that identity is not disclosed through file properties or captions."

Description

Strip identifying metadata (e.g., EXIF, XMP, PDF info dictionaries, author/producer fields) and remove textual brand mentions from document structures, slide master footers, and OCR-extracted text layers. Regenerate sanitized PDFs and images while preserving technical metadata required for rendering (dimensions, color profiles). Update alt text and captions to neutral descriptors to prevent identity leakage via accessibility channels. Provide configurable whitelist/blacklist rules per program and log all removed/retained fields for compliance review.

Acceptance Criteria

Image EXIF/XMP Identifier Redaction

Given an input image file (JPEG, PNG, or TIFF) containing EXIF/XMP/IPTC fields with identifying values (e.g., Author, Artist, Copyright, CameraSerialNumber, Software, Creator, Location, Contact, Organization) And a program profile with a blacklist of identifying metadata fields and a whitelist of technical fields [PixelXDimension, PixelYDimension, Orientation, ColorSpace/ICCProfile, DPI] When the file is processed by Metadata & Textual Brand Scrub Then all blacklisted fields are removed or blanked in the output file And all whitelisted technical fields are preserved unchanged And the output format matches the input format and the image pixel dimensions and ICC profile are identical to the source And the visual difference between source and output is <= 0.1% RMS, with no added artifacts or cropping And a compliance log entry is created listing each removed/preserved field and the action taken

PDF Info Dictionary and XMP Brand Scrub

Given a PDF with Info dictionary keys {Title, Author, Subject, Keywords, Creator, Producer} and XMP metadata containing organization or brand strings And a program profile with blacklist rules for those keys and brand tokens When the PDF is processed Then all blacklisted Info dictionary keys are removed or set to empty And all brand strings are removed from XMP packets while preserving non-identifying technical entries (e.g., OutputIntent, page boxes, embedded font references) And page count, page dimensions, embedded fonts, and color profiles remain unchanged And the sanitized PDF opens without errors in standard readers and renders all pages successfully And a compliance log lists each removed key and redacted XMP fields with counts

Slide Master Footer Brand Text Removal

Given a PPTX with slide masters and layouts containing footer placeholders or text boxes including blacklisted brand tokens And a program profile with blacklist tokens and an optional neutral replacement policy When the file is processed and exported to sanitized PPTX and PDF Then all instances of blacklisted brand text in master and slide footers are removed or replaced according to policy across 100% of slides And slide numbers, date placeholders, and other non-brand footer content are preserved And no slide element reflows by more than 2 px in x or y compared to baseline rendering And a compliance log identifies each slide id/master id where changes occurred

OCR Text Layer Brand Token Removal

Given a scanned PDF that visually contains blacklisted brand tokens and lacks a reliable text layer And OCR processing is enabled for the program profile When the PDF is processed Then an OCR text layer is generated for all pages And all occurrences of blacklisted brand tokens in the OCR text layer are removed or replaced with a neutral token "[redacted]" while preserving coordinates and reading order And searching the sanitized PDF for any blacklisted token returns zero matches; searching for non-brand text present in the original returns matches And if a token is whitelisted for the program, it is preserved And a compliance log includes counts of tokens removed/replaced per page

Accessibility Alt Text and Caption Neutralization

Given a tagged PDF or PPTX with images/figures whose alt text or associated captions contain blacklisted brand tokens And a program profile specifying neutral descriptors (e.g., "image", "diagram", "institution logo") When the file is processed Then all brand tokens are removed from alt text and captions or replaced with the configured neutral descriptors And the document tag tree remains valid and passes an automated accessibility check at the same conformance level as the source And screen reader extraction yields the neutral descriptor without exposing brand identity And whitelisted tokens are preserved And a compliance log lists each element id where alt/caption text was changed

Per-Program Whitelist/Blacklist Rules and Precedence

Given a program-level configuration with blacklist tokens ["Acme University", "AcmeU", "AU"] and whitelist tokens ["NIH"] And normalization is case-insensitive and diacritic-insensitive with Unicode NFKC applied When documents are processed Then blacklist matches are applied across document structures, OCR text layers, and metadata with whole-word and phrase matching that tolerates punctuation and line breaks And whitelist tokens take precedence over blacklist (whitelisted tokens are retained even if also present in blacklist) And a test document containing the tokens results in 100% of blacklisted tokens removed and 0% of whitelisted tokens removed And a compliance log shows the active configuration version and hash used for processing

Compliance Audit Log and Export

Given a batch of processed files When an admin requests the compliance log for a specific file or batch Then the system returns an export in JSON and CSV within 2 seconds for files ≤ 50 MB and ≤ 1,000 redactions And each log entry includes file id, program id, processing timestamp (UTC), processing engine version, configuration hash, and a list of actions (field/text removed or retained) with counts, storing only salted SHA-256 digests of original values And logs are immutable (append-only) and available for download for at least 1 year per retention policy

Batch Processing & Performance SLA

"As a program manager, I want large batches to process quickly with reliable status updates so that application windows aren’t delayed by redaction."

Description

Implement a scalable processing queue with parallel workers and autoscaling to handle peak submission volumes. Define and monitor SLAs (e.g., 95th percentile completion under target time for typical 50-page PDFs at 300 DPI). Show per-file progress and estimated time remaining in the UI, support retries and dead-letter queues, and enforce per-tenant resource limits. Prioritize jobs near program deadlines and emit webhooks/callbacks to update submission status in MeritFlow. Expose metrics and alerts for operational observability.

Acceptance Criteria

95th-Percentile Completion Time SLA (50-page @300 DPI)

Given a batch of 1,000 representative 50-page, 300 DPI PDFs and normal system load When they are submitted to LogoSweep processing Then the 95th percentile end-to-end completion time per file is <= the configured SLA target T seconds And the 99th percentile is <= 1.5 × T And measurement excludes time waiting for user upload but includes queue wait + processing

Autoscaling Parallel Workers at Peak Volume

Given sustained queue backlog exceeds the configured scale-up threshold for 2 minutes When autoscaling is enabled Then worker count scales up within 60 seconds to achieve the target concurrency C (up to max M) And median queue wait time stabilizes below the configured target W within 5 minutes And when backlog drops below the scale-down threshold for 10 minutes Then workers scale down to the configured minimum m without interrupting in-flight jobs

Per-File Progress and ETA in UI

Given a file is in processing When a user views its status page Then percent progress is displayed and updates at least every 5 seconds without full page reload And an ETA is shown once progress >= 25% with median absolute percentage error <= 20% over a test set And progress/ETA persist across page refresh and after transient network loss And the UI shows 'Queued', 'Processing', 'Completed', 'Failed', and 'Retrying' states with timestamps

Retries, Idempotency, and Dead-Letter Handling

Given a transient error (e.g., timeout, HTTP 5xx) occurs during processing When the job is retried automatically Then it is retried up to N times with exponential backoff and jitter while preserving an idempotency key And duplicate deliveries do not produce duplicate outputs And if a non-retryable error occurs or retries are exhausted Then the job moves to the dead-letter queue with error details, last 100 log lines, and correlation IDs And authorized operators can requeue DLQ items individually or in bulk

Deadline-Aware Prioritization with Per-Tenant Resource Limits

Given multiple tenants with configured per-tenant concurrency caps and jobs tagged with program deadlines When the scheduler orders work under contention Then jobs with deadlines within the next 24 hours are prioritized ahead of non-urgent jobs And per-tenant caps are enforced so no tenant exceeds its configured concurrency And no tenant receives less than 80% of its entitled share over any rolling 15-minute interval And starvation is prevented: every tenant with queued work starts at least one job within 2 minutes

Webhooks/Callbacks for Submission Status Updates

Given a job transitions to Completed, Failed, or Requires-Attention When webhook endpoints are configured for the tenant Then a webhook is sent within 5 seconds with a signed HMAC (SHA-256) over the payload and timestamp And delivery is at-least-once with exponential backoff for up to 24 hours until a 2xx is received And event ordering per file is preserved And idempotency keys are provided so receivers can dedupe And 4xx (except 429) cease retries; 5xx or timeouts continue retries; 410 disables the endpoint

Metrics, Dashboards, and Alerts for Operational SLA

Given the system is running in production When metrics are scraped by Prometheus/OpenTelemetry Then the following are exported: queue length, queue wait time, processing time p50/p95/p99, active workers, throughput, retry counts, DLQ size, webhook success rate, and autoscaler events And a default dashboard displays these with 24h and 7d views And an alert fires within 2 minutes when p95 completion time > T for 5 consecutive minutes, or DLQ size > D, or no active workers for 60 seconds And alerts are routed to the on-call channel with runbook links

Redaction Audit Trail & Versioning

"As a compliance officer, I want a complete audit trail of redactions and approvals so that we can demonstrate blind review integrity if challenged."

Description

Create an immutable audit trail that records detection outputs, confidence scores, manual edits, mask coordinates, and metadata changes for each file version. Retain originals securely and generate downloadable redaction reports summarizing actions taken and rationale. Provide version diffs and rollback to previous redactions when needed, governed by program-level retention policies. Ensure tenant isolation and offer API export of audit data for compliance and external review.

Acceptance Criteria

Immutable Audit Log Capture on Auto-Detection

Given a file is uploaded and auto-detection runs When detection completes successfully Then an audit entry for version V1 is appended capturing file_id, version_id, tenant_id, program_id, algorithm_version, detection_list(type,page,frame,bbox[x,y,w,h],confidence[0..1]), timestamp(UTC ISO8601), created_by=system, version_checksum(SHA-256) And the audit store is append-only: any update/delete attempt returns 403 and leaves entry content_hash unchanged And entries contain content_hash and previous_hash; verifying the chain for the last 100 entries succeeds And detection_list count and coordinates match the rendered masks within ±1 pixel

Manual Edit Logging with Mandatory Rationale

Given a permitted user edits a mask (add/remove/resize/move) on a file When they submit the change with a rationale Then a new version Vn is created and the audit logs action_type, before_coords, after_coords, page/frame, mask_id, user_id, timestamp, rationale(min 5 chars) And attempts to save without a rationale are blocked with validation error and no version is created And undo/redo are logged with linkage to original action_id; metadata edits (type, opacity, FP/TP) are captured And filtering audit by user_id and action_type returns deterministic counts equal to UI totals

Version Diff and Rollback

Given two versions Vi and Vj of the same file When a diff is requested Then the system returns added/removed/modified masks with ids and coordinate deltas; totals per page equal audit counts When a rollback to Vk is requested by a user with "Manage Versions" permission Then a new version Vn+1 is created identical to Vk (diff is empty) and the audit logs initiator and reason; history is preserved And users without permission receive 403 and no new version is created

Redaction Report Generation and Download

Given a redacted file version exists When "Download Redaction Report" is requested Then PDF and CSV generate within 15s including file_id, version_id, checksums(original,redacted), timestamps, algorithm_version, per-action counts, masks(id,page,bbox,confidence,source), rationales, and report signature And report contents 1:1 reconcile with audit entries and pass schema validation And only authorized roles can download; access is logged; re-downloading the same version yields identical hashes

Retention Policy Enforcement and Original Preservation

Given a program retention policy of N days When a file is ingested Then the original is stored read-only and accessible to authorized roles until expiry_timestamp; audit records retention_expiry When expiry passes Then attempts to access originals or pre-expiry versions return 404/410; a tombstone audit entry is appended recording purge scope and timestamp; reports are purged unless keep_reports=true; audit is retained if retain_audit=true And early purge is allowed only when policy allows; action requires confirmation and is logged

Tenant Isolation and Access Controls

Given two tenants A and B When a user from B attempts to access A's files/audit via UI or API Then responses are 404/403 with no cross-tenant data leakage; audit remains unchanged And audit entries always include tenant_id and program_id matching the authenticated context; attempts to set tenant_id via API are rejected with 400 And only roles with View Audit, Export Audit, Manage Versions scopes can perform those actions; violations are denied and logged

Audit Data API Export

Given an authorized token with Export Audit scope When calling GET /exports/audit with filters (program_id, file_id, version range, date range, action_type, user_id) and format (JSON|CSV) Then synchronous responses return ≤10k records per page; larger jobs run async and provide a signed URL within 2 minutes; tenant_id is inferred from auth and cannot be overridden And export payload contains required fields and passes schema and checksum verification; a 100-record sample matches UI audit 1:1 And unauthorized/overscoped requests return 401/403; all exports are logged with requester, filters, and counts

Redaction QA

Confidence scores, smart sampling, and side-by-side before/after views to verify redactions fast. Bulk-approve accurate batches, route edge cases to a review queue, and export proof packs that satisfy audit requirements in minutes.

Requirements

Confidence Scoring Engine

"As a program manager, I want confidence scores on each redaction so that I can set thresholds and minimize manual checks without risking PII leaks."

Description

Compute confidence scores at entity- and document-level for all detected PII types (names, emails, phone numbers, addresses, affiliations, custom fields) and persist them alongside redaction metadata. Expose thresholds configurable per program and cohort, surface scores in UI and API, and use them to drive sampling, routing, and bulk actions. Include calibration tools and backtesting against labeled sets, with model/version tagging and change logs. Integrate into MeritFlow’s anonymization gate so submissions only progress to blind review when aggregate confidence meets defined thresholds. Expected outcome: materially reduce manual review while maintaining compliance-grade assurance.

Acceptance Criteria

Entity-Level Confidence Scoring for PII Types

Given a document with detected PII of types: names, emails, phone numbers, addresses, affiliations, and configured custom fields When the confidence scoring engine runs Then each detected PII entity is assigned a score between 0.00 and 1.00 with at least 2-decimal precision And the score is persisted alongside the entity’s redaction metadata And the PII type, detection source, and model/version tag are stored with the score And overlapping or nested entities have independent scores recorded per entity And entities with low confidence still receive a numeric score (no nulls) And re-running with the same model/version and input yields identical entity scores

Document-Level Aggregate Confidence and Persistence

Given a document containing one or more scored PII entities When computing the document-level aggregate confidence Then an aggregate score in the range [0.00, 1.00] is produced using the documented method And the aggregate score is persisted in the document’s redaction metadata And the computation timestamp and model/version tag are recorded And the aggregate score updates when underlying entity scores change And recomputation with unchanged inputs yields the same aggregate score

Threshold Configuration per Program and Cohort with Change Logs

Given an admin with permission to configure redaction thresholds When they set entity- and document-level thresholds for a specific program and cohort Then the thresholds are saved and applied only to that program and cohort And default thresholds are applied when none are configured And each change is logged with who, when, before/after values, notes, and model/version where applicable And effective-from timestamps are supported for future-dated changes And the currently effective thresholds are retrievable via UI and API

UI and API Exposure of Scores and Threshold Warnings

Given a reviewer opens the Redaction QA side-by-side view When redactions are displayed Then each redacted entity shows its confidence score and PII type And the document header shows the aggregate confidence score And scores below configured thresholds are visually flagged with a legend And hovering or expanding reveals model/version and timestamp for the score And the API returns entity and aggregate scores, thresholds in effect, and model/version for the document And API schemas constrain scores to [0,1] and include PII type and entity IDs without exposing unredacted content

Sampling, Routing, and Bulk Actions Driven by Confidence

Given program/cohort thresholds and sampling rules are configured When a batch of scored documents is processed Then documents with aggregate scores >= auto-approve threshold are eligible for bulk approval And documents with any entity score < entity threshold are routed to the review queue And a smart sampling percentage is applied to auto-approve-eligible documents for spot checks And users can preview, filter, and confirm the bulk-approve set before committing And all routing and bulk actions create audit entries capturing counts, thresholds used, and model/version tags

Calibration Tools and Backtesting Against Labeled Sets

Given a labeled dataset is selected for backtesting When the scoring engine is evaluated on the dataset Then the system computes and displays precision, recall, and F1 at multiple threshold cutoffs And provides PR/ROC summary metrics and suggested threshold candidates for target precision/recall And results are tagged with model/version and dataset identifier and are stored with change logs And rerunning on the same dataset and model/version yields identical metrics And reports are exportable for audit (CSV/JSON)

Anonymization Gate Enforcement by Aggregate Threshold

Given an aggregate confidence threshold is configured for a program/cohort When a submission attempts to progress to blind review Then progression is allowed only if the document’s aggregate score meets or exceeds the threshold And if the threshold is not met, the submission is blocked and routed to the review queue with a clear reason message And an event is recorded including scores, thresholds, model/version, and user/system actor And gate status and reason are available in UI and API And progression reevaluates automatically when scores or thresholds change

Smart Sampling Controls

"As a grants coordinator, I want smart sampling that auto-selects documents for QA based on risk so that I can validate anonymization efficiently and defensibly."

Description

Provide a configurable, statistically sound sampling module that selects documents and entities for QA based on confidence distributions, PII types, cohort risk, and recent drift. Allow users to set target confidence level and margin of error, support stratified and adaptive sampling, and auto-generate QA batches with coverage tracking. Recompute samples as new documents arrive or thresholds change, and record sampling methodology for audit. Integrates with queues and bulk-approval to translate sample outcomes into pass/fail decisions for the entire batch.

Acceptance Criteria

Sample Size Computation from Confidence and Margin of Error

Given population size N=10,000, target confidence=95%, margin of error=3%, and default p=0.5 When the user generates a sample Then the system computes required sample size using finite population correction and displays 964 ±1 as the required sample count and the parameters used Given population size N=800, target confidence=95%, margin of error=5%, and p=0.5 When the user generates a sample Then the required sample count equals 260 ±1 and never exceeds N Given custom p=0.2 and a fixed random seed When the user generates a sample Then the required sample size adjusts accordingly and the same items are selected on rerun with the same seed

Stratified Sampling by PII Type, Confidence Band, and Cohort Risk

Given stratification by PII Type {SSN, Address, Name}, Confidence Band {0.0–0.7, 0.7–0.9, 0.9–1.0}, and Risk Cohort {High, Medium, Low}, min per stratum=5, and allocation=Proportional When the user generates a sample Then sample counts per stratum are proportional to stratum population, rounded by Largest Remainder, the sum equals the global required sample, and any stratum with population <5 is fully sampled (census) Given allocation=Equal per stratum When the user generates a sample Then each non-empty stratum receives an equal share subject to min-per-stratum and total rounding constraints Given an oversample factor of 1.5 for (Confidence Band 0.0–0.7 ∧ Risk=High) When the user generates a sample Then the oversample factor is applied before rounding and coverage is reported per stratum

Adaptive Sampling Responds to Drift

Given drift thresholds configured as mean confidence delta ≥ 5 points or KL divergence ≥ 0.1 over a 7-day window per cohort When any cohort exceeds any threshold Then the sampling rate for its strata increases by multiplier m=2 (capped at 50% of incoming items) and the change is applied to the next QA batch within 5 minutes Given thresholds return below limits for 3 consecutive windows When the system evaluates drift Then sampling reverts to baseline for the affected cohorts Given no drift conditions are met When the system evaluates drift Then sampling rates remain unchanged Then all adjustments are recorded with timestamp, metrics, cohort identifiers, and the active policy configuration

Auto-Regeneration on New Data or Threshold Changes

Given a generated sample version v1 at time t0 When new documents increase the population by ≥ 2% or the user changes target confidence, margin of error, or stratification settings Then the system recomputes the sample within 5 minutes, creates version v2, and updates associated QA batches Then previously QA-completed items remain locked; pending sampled items may be replaced only if removal does not drop any stratum below 95% of its target Then a human-readable diff of added/removed items is displayed and logged, and the prior version remains downloadable for audit

Coverage Tracking Across Strata and Cohorts

Given a QA batch with stratified sampling When the user views Coverage Then the system displays for each stratum: target sample, sampled, completed, remaining, and percent coverage, and totals roll up by PII type and cohort Then status indicators render as Green (≥100% of target), Amber (80–99%), Red (<80%) When the user exports coverage Then the CSV includes batch id, stratum keys, targets, actuals, percentages, and timestamp

Queue Integration and Batch-Level Pass/Fail Propagation

Given an AQL threshold configured at 1.5% defect rate When sample review completes with observed defect rate ≤ 1.5% Then the batch status is Pass and all non-sampled items in the batch are auto-approved and removed from the review queue Given observed defect rate > 1.5% When sample review completes Then the batch status is Fail and the batch is routed to the Review Queue with an expanded sample size computed to meet the configured confidence and margin of error Then the decision, thresholds, observed metrics, and affected item IDs are recorded in batch history

Audit Log and Exportable Proof Pack

Given any generated or regenerated sample When the user selects Export Proof Pack Then the system produces a package within 30 seconds containing: sampling inputs (confidence, margin of error, p, population snapshot time), stratification scheme, allocation method, random seed, selected IDs, drift metrics at selection time, version history, QA outcomes, batch pass/fail decision, user IDs, timestamps, and a cryptographic hash Then the package is reproducible with the same seed and inputs and its hash matches the value stored in the audit log When viewing audit for a batch Then each sample version shows who/when, parameters, cohort risk factors, and rationale for any adaptive changes

Side-by-Side Redaction Diff Viewer

"As a reviewer lead, I want a side-by-side before/after viewer so that I can quickly verify and correct redactions with full context."

Description

Deliver a performant before/after viewer with synchronized scrolling, page thumbnails, zoom, and keyboard shortcuts. Visually highlight redacted regions and PII labels, show per-entity confidence and reason codes, and allow mask toggle to inspect context without downloading originals. Support PDF, DOCX, and common image formats, preserve layout fidelity, and enable per-entity accept/reject with instant updates to redaction metadata and audit log. Ensure WCAG-compliant interactions and low-latency rendering for long documents.

Acceptance Criteria

Synchronized Side-by-Side Navigation

Given a multi-page document is opened in the side-by-side viewer with zoom sync enabled When the user scrolls either the left (before) or right (after) pane Then the opposite pane scrolls to the same page and vertical offset with a mismatch of <= 10 px or <= 0.5% of viewport height, whichever is greater And the current page indicator and thumbnail selection stay in sync across both panes Given the user changes zoom to 50%, 100%, 150%, 200%, or fit-to-width When zoom is changed in either pane Then both panes reflect the same zoom level within 1 animation frame (<= 16 ms) when sync is enabled, and an independent-zoom badge is shown when sync is disabled Given thumbnails are visible When a thumbnail is clicked Then both panes navigate to that page within 300 ms (95th percentile), and the next and previous two pages are pre-rendered

Redaction Overlays and Metadata Display

Given redacted entities exist with type, confidence (0–1), and reason code When the after-view loads a page Then all redaction regions are drawn as opaque masks with visible outlines and PII labels, and hovering or focusing an entity shows a tooltip with entity type, confidence (rounded to 2 decimals), and reason code And overlapping entities are individually focusable via keyboard, with a deterministic focus order (top-to-bottom, left-to-right) And the before-view shows non-obscuring outlines for the same entities aligned within <= 2 px at 100% zoom And colors and line styles differ by entity type without relying on color alone

Mask Toggle for Context Inspection (No Download)

Given the user is viewing the after pane with redactions applied When the user toggles Mask Off Then the underlying content is revealed in the after pane without initiating any file download, export, or print action And copy, paste, print, and download controls are disabled, and a “Preview—Not Exportable” watermark overlays the page And the toggle action is logged with user, timestamp, page, and entity IDs (if scoped) in the audit log And toggling Mask On re-applies masks within 150 ms (95th percentile) and removes the watermark

Per-Entity Accept/Reject with Instant Audit Update

Given an entity overlay is focused or selected When the user presses A (accept) or R (reject) or activates the corresponding UI controls Then the entity’s status updates in the UI with a visual badge and is persisted to redaction metadata within 300 ms (95th percentile) And the after-view updates to reflect the decision: accepted masks remain opaque; rejected masks are removed and replaced with a dashed-outline indicator on both panes within 200 ms And an audit log entry is created containing user, timestamp, entity ID, action, and optional reason, with durability confirmed within 1 s And the user can undo (Ctrl/Cmd+Z) and redo (Ctrl/Cmd+Shift+Z) the decision with the same timing guarantees

Multi-Format Support and Layout Fidelity

Given a supported file is opened (PDF, DOCX, PNG, JPG, TIFF) When the document loads Then both panes render all pages and page counts match the source And at 100% zoom, entity bounding boxes align to within <= 2 px for top-left coordinates and width/height versus source coordinates for PDF and converted DOCX And for raster images, pixel dimensions and DPI are preserved; for multi-page TIFFs, page ordering is preserved And if an unsupported format is provided, the user sees a clear error with the list of supported formats and no viewer crash

Low-Latency Rendering for Long Documents

Given a long document (up to 500 pages and 150 MB) is opened When the viewer initializes Then first contentful render of page 1 in both panes occurs within 2 s (95th percentile) And navigating via Page Down or thumbnail results in the target page fully rendering within 300 ms (95th percentile) after warm-up and within 700 ms cold-load And scroll input-to-paint latency is <= 50 ms (95th percentile) And zoom-in/out completes visible reflow within 150 ms (95th percentile) And no main-thread stalls > 200 ms occur more than once per minute during continuous scroll (95th percentile)

WCAG 2.1 AA Accessibility and Keyboard Operability

Given a keyboard-only user navigates the viewer When performing all core actions (page nav, zoom, mask toggle, entity focus, accept/reject) Then all controls are reachable via Tab/Shift+Tab with visible focus indicators and no keyboard traps And the following shortcuts work and are announced in help: Arrow keys scroll; PageUp/PageDown navigate pages; Home/End jump to first/last page; +/- adjust zoom; 0 fits to width; T toggles thumbnails; M toggles mask; A accept; R reject; Esc closes dialogs And all actionable controls have accessible names/roles/states (ARIA) and tooltips with programmatic labels And color contrast for text and overlays is >= 4.5:1, and non-color cues (patterns/icons) indicate states And screen readers announce focused redaction overlays with entity type, confidence (to 2 decimals), reason code, page, and status

Bulk Batch Approval

"As a QA reviewer, I want to bulk-approve accurate batches so that I can clear large volumes faster and keep cycles on schedule."

Description

Enable batch-level approve/reject actions driven by sampling results and confidence thresholds. Provide safeguards such as preview summaries, exception counts, and required rationale for rejections. Support partial approvals (exclude flagged entities), undo/rollback, and automatic state transitions (e.g., Ready for Blind Review). Emit notifications and webhook events, and record all actions with user, timestamp, and criteria used for traceability.

Acceptance Criteria

Approve Batch When Sampling Meets Thresholds

Given a batch with configured sampling rules and confidence thresholds And sampling has completed for the batch And the aggregate results meet or exceed the configured confidence threshold and are within the allowed exception rate When the user opens the batch approval modal Then the Approve action is enabled And the modal displays sample size, pass rate, mean/median confidence, and exception count And upon confirming Approve, all non-flagged redaction entities are marked Approved And flagged entities are excluded from approval and routed to the Review Queue And the batch status updates according to the state transition rules

Reject Batch Requires Rationale and Shows Exception Summary

Given a batch where the user chooses Reject When the Reject action is selected Then a rationale text field is required (minimum 10 characters) before confirmation is enabled And the modal displays total documents, exception counts, and top exception reasons from sampling And upon confirming Reject, no entities are approved And the batch status updates to Rejected And the rationale is stored in the audit log

Partial Approval Excludes Flagged Entities

Given a batch containing flagged redaction entities When the user approves the batch with the "Exclude flagged entities" option selected Then only non-flagged entities are approved And flagged entities remain Pending and are added to the Review Queue And the confirmation dialog shows counts of approved entities, excluded flagged entities, and remaining pending entities before confirmation

Undo/Rollback of Last Batch Decision

Given a batch with a most recent decision within the configured rollback window and with no downstream processing started When the user selects Undo Decision Then the system reverts the batch and entity states to their prior values And emits a rollback notification and webhook event And records an audit log entry linking the rollback to the original decision, including actor, timestamp, and reason (if provided)

Automatic State Transitions After Decision

Given a batch decision has been confirmed and persisted When entity-level updates are completed Then if all entities are Approved, the batch state transitions to Ready for Blind Review And if some entities are Approved and some remain Pending due to exclusions, the batch state transitions to Partially Approved And if the decision is Reject, the batch state transitions to Rejected

Notifications and Webhooks on Batch Decisions

Given a batch decision event (Approve, Partial Approve, Reject, Undo) is persisted When the event is processed Then in-app notifications are sent to watchers of the collection/program And email notifications are sent to configured recipients (if enabled) And a webhook is emitted containing event type, batch ID, actor, decision rationale (if any), counts (approved, excluded, pending), sampling/threshold snapshot, and timestamps And webhook deliveries retry per the configured policy on failure, with failures visible in an admin log

Comprehensive Audit Trail and Proof Pack

Given any batch-level decision or rollback is executed When the action completes Then an immutable audit record is written capturing actor, timestamp (UTC), action type, sampling configuration and results, thresholds used, decision rationale (if any), entity/document counts affected, and pre/post batch states And the system can export a proof pack that includes the audit record, decision summary, and links to side-by-side before/after views for sampled items And the proof pack is downloadable by authorized users from the batch details page

Review Queue & Routing Rules

"As a compliance officer, I want edge cases routed to a review queue with assignments and SLAs so that nothing risky slips through before blind review."

Description

Create a configurable queue that automatically routes low-confidence items, policy exceptions, and reviewer flags to designated assignees based on program, workload, and SLA rules. Provide prioritization, tagging, comments/mentions, and conflict-safe assignment. Display per-queue KPIs (aging, at-risk items) and enforce escalation when SLAs are breached. Integrate with MeritFlow permissions and notifications to ensure secure, timely handling of edge cases.

Acceptance Criteria

Automatic Routing of Edge Cases to Review Queue

Given program P has routing rules with confidence_threshold = 0.80 When a redaction job for application A in program P completes with confidence 0.72 Then A is enqueued into P's Review Queue within 60 seconds and route_reason = "low-confidence" Given program P has a policy exception rule for "passport_number" When application A contains a detected passport number Then A is enqueued within 60 seconds with route_reason = "policy-exception:passport_number" Given a reviewer of application A clicks "Flag for Review" When the action is confirmed Then A appears in P's Review Queue within 10 seconds with route_reason = "reviewer-flag" Then each routed item records rule_id, timestamp, and actor in an immutable audit log entry And the same item is not enqueued twice for the same rule (idempotent routing)

Workload-Based Assignment with Conflict Safety

Given queue Q has assignee_pool = {R1,R2,R3}, max_active_per_reviewer = 5, and assignment_mode = "auto" When item I enters Q Then I is auto-assigned within 10 seconds to the reviewer in the pool with the lowest number of active queue items And the selected reviewer has no conflict-of-interest with I (not the applicant, not in I.conflicts, not disallowed by program conflict rules) If all reviewers are conflicted or at capacity Then I remains unassigned with status = "Needs Assignment" And an alert is sent to Q.owner within 60 seconds Given N items enter concurrently When auto-assignment runs Then each item has exactly one assignee or status = "Needs Assignment" (no duplicate assignments) When a user attempts to manually assign I to a conflicted reviewer Then the action is blocked with an error explaining the conflict rule violated

Queue Prioritization and Tagging

Given queue Q has prioritization rule priority_score = f(SLA_proximity, risk_score) defined When items are enqueued Then each item receives a computed priority_score and Q sorts by descending priority by default Given a user sets an item's priority override to High/Normal/Low When saved Then the override is immediately reflected in sorting and captured in the audit log with actor and timestamp Given tagging rules (e.g., add tag "PII-Passport" when passport_number detected) When items enter Q Then matching tags are auto-applied And users with permission "Tag:Edit" can add/remove tags manually When filtering by tag, priority, program, assignee, or SLA status Then results return in under 2 seconds for up to 10,000 items And bulk actions (reassign, tag) apply only to the filtered set after confirmation showing exact item count

Comments and Mentions with Notifications

Given a user with permission "Comment:Create" opens item I When they post a comment containing @alice and @team:Reviewers Then the comment is saved with comment_id, author_id, and created_at And both Alice and all members of team Reviewers receive an in-app notification within 60 seconds and an email within 5 minutes (if email notifications are enabled) When a mention targets a user without access to item I Then the system prevents posting and displays a validation error When a moderator deletes a comment Then a tombstone entry remains in the thread with who and when And the original content is not displayed All notification events include item_id, program_id, and a deep link to I

Permission-Gated Queue Visibility and Actions

Given user U lacks permission "Queue:View" for program P When U navigates to P's Review Queue Then the system returns 403 and does not leak item counts or metadata Given user U has "Queue:View" but not "Queue:Assign" When U attempts to assign or reassign an item Then the action is blocked with 403 and a clear error message Row-level security limits visibility to programs where U has access When test items exist for P1 and P2 and U only has access to P1 Then U sees 0 items from P2 All access decisions are audit-logged with user_id, action, resource_id, decision, and reason

SLA Tracking, KPIs, and Escalation

Given queue Q has SLA = 72 hours and at_risk_threshold = 80% When items are present Then the queue UI displays KPIs: total_items, avg_age_hours, items_at_risk, items_breached_sla, oldest_item_age And KPI values refresh at least every 60 seconds When an item consumes >= at_risk_threshold of SLA time Then it is labeled "At Risk" and included in items_at_risk counts When an item breaches the SLA Then the item is marked Breached And the system notifies Q.owner and the escalation list within 60 seconds And, if backup_pool is configured, the item is auto-reassigned to the backup_pool Escalation notifications repeat per policy until the item is acknowledged or resolved And all SLA state changes and notifications are audit-logged with timestamps

Audit Proof Pack Export

"As an auditor or funder liaison, I want exportable proof packs so that I can demonstrate our redaction QA process meets audit requirements."

Description

Generate a tamper-evident export (ZIP/PDF) containing originals and redacted versions, decision logs, sampling methodology and parameters, reviewer actions with timestamps, confidence thresholds, model/version identifiers, and cryptographic checksums. Provide one-click export per program/batch, include a human-readable summary and machine-readable JSON, and archive exports to program records. Ensure exports meet common funder and institutional audit requirements.

Acceptance Criteria

One-Click Export for a Selected Program Batch

Given I am an authorized Program Manager on Program P with Batch B containing completed redactions When I click “Export Audit Proof Pack” for Batch B Then an export job starts and a progress indicator is shown with estimated time to completion And the export completes within 2 minutes for batches up to 1,000 items or 2 GB total size And a downloadable ZIP is provided named <Program>_<Batch>_<UTC-Timestamp>.zip And the ZIP contains summary.pdf (human-readable) and audit.json (machine-readable) And the ZIP contains Originals/ and Redacted/ folders with one-to-one file pairing And audit.json includes a file_mappings array linking original and redacted filenames And the export action is recorded in the audit trail with user, timestamp, program, and batch identifiers

Tamper-Evident Manifest and Cryptographic Integrity

Given a completed audit proof pack ZIP When I verify file checksums using the included manifest (manifest.json) and SHA-256 hashes Then every file’s SHA-256 matches the manifest And a detached signature (manifest.sig) validates against the MeritFlow signing certificate whose fingerprint is shown in summary.pdf and configured in Admin settings And any modification to any file causes checksum verification or signature validation to fail And summary.pdf displays the overall manifest hash and signing key identifier

Complete Audit Metadata in Summary PDF and JSON

Given an export was generated for Batch B in Program P When I open summary.pdf and audit.json Then both documents include: decision logs (decision, reviewer/user id, rationale if provided), reviewer actions with UTC timestamps, sampling methodology name and parameters (e.g., strategy, seed, sample size, stratification keys), applied confidence thresholds per field/type, model identifiers (model name, version, checksum or build id), and generator/version of the export service And audit.json conforms to schema version 1.0 (validated against the published JSON Schema) And summary.pdf contains section summaries with counts (items exported, redactions applied, reviewers involved) And if any required field is missing, the export fails with a descriptive error listing missing fields and remediation steps

Automatic Archival to Program Records

Given an export for Batch B completes successfully When the job finishes Then the proof pack is archived under Program P > Exports with an immutable URI, version number, created timestamp, and size And access controls apply: Admins and Program Managers can download the full ZIP; Reviewers can access summary.pdf only; others are denied And a retention policy tag is applied based on Program P settings And subsequent exports for the same batch create a new version without overwriting prior versions And the archived entry appears in the Exports list within 30 seconds and is searchable by program, batch, date, and version

Compliance Validation Against Audit Checklist

Given Program P has selected the “Common Audit Requirements v1” checklist in settings When exporting Batch B Then the system validates the proof pack against the checklist items before finalizing And if any requirement fails, the export is blocked and the user sees actionable messages mapped to specific checklist items And the completed checklist with pass/fail per item is embedded in summary.pdf and audit.json And an Admin can override a failure only with a mandatory justification, which is recorded in the audit trail

Robust Error Handling and Resumable Exports

Given an export is in progress for Batch B When a transient storage or network error occurs Then the job retries up to 3 times with exponential backoff without creating duplicate archives And partially written artifacts are cleaned up and not exposed to users And on terminal failure, the user is notified with a correlation ID and can safely re-trigger the export And system logs capture error class, stack trace, affected item counts, and retry outcomes for observability

Policy Packs

Click-to-apply redaction templates aligned to GDPR, FERPA, HIPAA-lite, and institutional policies. Tunable PII categories and retention windows let teams standardize blind-review practices across programs without rebuilding rules each cycle.

Requirements

Pack Catalog & Versioning

"As a compliance officer, I want a catalog of prebuilt and versioned policy packs so that I can confidently apply the right standard and manage changes without disrupting active programs."

Description

Provide a library of prebuilt, validated policy packs aligned to GDPR, FERPA, HIPAA-lite, and common institutional policies, with the ability to preview rules, compare versions, and pin a program to a specific pack version. Each pack includes metadata (scope, default PII categories, default retention windows, rule provenance, last review date) and a changelog. Versioning must be backward-compatible, allow deprecation with end-of-support dates, and support safe upgrades with a diff view and impact analysis across programs. Packs can be cloned and edited to create institution-specific variants, then exported/imported between environments. Multi-tenant isolation ensures packs and edits are scoped to an organization. Integration points include the program template builder (select pack at creation), automation engine (apply on submission), and reviewer portal (display pack label and effective rules).

Acceptance Criteria

Catalog Listing and Metadata Visibility

Given an Org A admin opens the Policy Packs Catalog When the catalog loads Then the list includes prebuilt packs tagged GDPR, FERPA, HIPAA-lite, and at least one Institutional Baseline And each pack shows scope, default PII categories (count and list preview), default retention windows, rule provenance, and last review date And packs can be filtered by policy tag and status (Active, Deprecated) and searched by name And packs can be sorted by last review date descending

Rule Preview, Changelog, and Version Diff

Given a user opens a pack detail page for version vA When they select Preview Rules Then the full rule list displays with default PII category toggles and retention window values And each rule shows provenance metadata (source, reviewer, review date) And a Changelog tab lists dated entries with author and summary for at least the last 5 versions When the user selects Compare and chooses versions vA and vB Then a diff view highlights Added, Modified, and Removed rules with counts And each changed rule shows id, name, category, and change type And the user can download the diff as JSON

Program Pinning and Runtime Enforcement

Given a program owner is creating Program X in the template builder When they select pack GDPR and choose version vA and enable Pin to version Then Program X stores packId and version vA in its configuration And the automation engine applies rules from GDPR vA on submission processing for Program X And the reviewer portal displays the pack label and effective rules version on review pages for Program X And global updates to the pack do not change Program X behavior until an explicit upgrade is performed And an audit log records the pin action with user, timestamp, packId, and version

Deprecation and End-of-Support Lifecycle

Given pack version vA is marked Deprecated with an end-of-support date D When the current date is before D Then the catalog and pack detail show a Deprecated badge with EOS date And new pinning to vA is allowed only after the user acknowledges a warning modal When the current date is on or after D Then new pinning to vA is blocked with an error indicating end of support has been reached And existing programs pinned to vA continue to function and display an Unsupported badge with an Upgrade CTA And catalog filters can include/exclude Deprecated and EOS versions

Safe Upgrade with Impact Analysis

Given Org A has programs P1 and P2 pinned to GDPR vA When an admin initiates Upgrade to GDPR vB Then the system displays an impact analysis listing all affected programs and a diff summary per program And a backward-compatibility check runs and blocks the upgrade with reasons if breaking changes are detected; otherwise it proceeds And the admin can select specific programs to upgrade and must confirm the action And upon completion, selected programs store version vB, automation uses vB on subsequent submissions, and audit logs capture the upgrade And the admin can download the impact report as JSON or CSV

Clone and Edit Institution Variant with Tenant Isolation

Given an Org A admin views pack GDPR vA When they select Clone as Variant and name it "Org A GDPR vA.1" Then a new pack is created with variant-of metadata referencing GDPR vA and inherits scope, default PII categories, retention windows, and provenance And the variant is visible and editable only by Org A users; users from other organizations cannot see or access it And edits to the variant (rules, PII categories, retention windows) do not alter the source pack And the variant maintains its own changelog and version sequence starting at vA.1

Export/Import Between Environments Preserving Version Graph

Given an Org A admin selects a pack (and specific versions) in Sandbox When they export the selection Then a signed archive is generated containing metadata, rules, changelog, and the version graph with checksums When the admin imports the archive into Production for Org A Then the system validates tenant identity, schema/version compatibility, and checksums before applying changes And import creates new packs/versions or updates existing ones without duplicating identical versions And cross-tenant imports are rejected and name/id collisions across tenants are prevented And a dry-run preview lists creates/updates and conflicts before final confirmation

Configurable PII Taxonomy

"As a program administrator, I want to configure which PII categories are detected and how they are redacted so that blind-review rules match our institution’s policies without over- or under-redaction."

Description

Enable administrators to tune PII categories per policy pack, including enabling/disabling default categories, defining custom categories, and mapping categories to MeritFlow form fields and uploaded artifacts. Each category supports multiple detection strategies (pattern/regex, dictionary, ML classifier) with configurable confidence thresholds and test harnesses to validate sample data before rollout. Provide language-aware detection and file-type coverage for text fields, PDFs, Word docs, and images with OCR where applicable. Allow redaction styles per category (mask, remove, pseudonymize, hash) and controls for partial-field masking (e.g., last four digits). Changes to the taxonomy generate a new pack version and trigger safe reprocessing workflows. Provide a simulation mode to report would-be redactions without affecting live reviewer views.

Acceptance Criteria

Enable/Disable Default PII Categories

Given I am an administrator editing a Policy Pack And the pack contains default PII categories When I disable a default category and save the pack Then the disabled state is persisted to the pack version And new ingests and reprocessing for that pack do not apply the disabled category And the category is visibly marked as Disabled in the pack configuration UI And an audit log entry records the action with user, timestamp, category, and pack version

Create Custom Categories with Multi-Strategy and Language Configuration

Given I am creating a custom PII category in a Policy Pack When I enter a unique name and optional description And I configure at least one detection strategy (regex, dictionary, or ML classifier) And I set a confidence threshold between 0.00 and 1.00 for each strategy And I optionally scope strategies to one or more languages Then the system validates regex compilation, dictionary load, and classifier availability And rejects duplicate category names within the same pack And persists the category with strategies, thresholds, and language scopes to the draft pack version And exposes the category in the pack list with its configured strategies

Map Categories to Form Fields and Artifact Types with OCR Coverage

Given a PII category exists in the pack When I map the category to specific MeritFlow form fields and artifact types (Text, PDF, DOCX, Image) Then detection for that category is executed only on the mapped fields and artifact types And OCR is applied for images and scanned PDFs; native text extraction is used for text/PDF/DOCX where available And password-protected or unreadable files are flagged and excluded from auto-redaction with an actionable warning And the mappings are saved with the pack version and included in pack export/import

Test Harness Validation Gate Before Publish

Given a draft Policy Pack version with configured categories and mappings And a sample dataset is uploaded or selected (including multilingual samples where applicable) When I run the test harness Then the system reports per category and per strategy: sample hits with snippets, confidence scores, and aggregate precision/recall And allows me to adjust thresholds and rerun without leaving the screen And prevents publishing the draft until at least one successful test run has completed within the last 24 hours with no strategy errors And stores the test report with an ID and timestamp for auditing

Redaction Styles and Partial-Field Masking Behavior

Given a category has a selected redaction style (mask, remove, pseudonymize, or hash) And optional partial-field masking rules are defined (e.g., show last 4 digits) When I preview and apply redactions for test samples Then the output reflects the chosen style and partial masking rule consistently across fields and files And pseudonymization is deterministic within the same pack version And hashing uses a cryptographically secure algorithm (SHA-256 or stronger) with a pack-specific salt And live reviewer views never display the unredacted value for content governed by the category

Versioning and Safe Reprocessing Workflow

Given I modify any taxonomy element (category enable/disable, strategy, mapping, redaction style) When I save the changes Then the system creates a new Policy Pack version with an incremented semantic version And starts a safe reprocessing workflow that reprocesses affected submissions in the background And pins reviewer views to the last stable pack version until reprocessing completes or is explicitly switched And displays progress (queued, processing, complete) and allows pause/resume And records a version diff and workflow events in the audit log And allows rollback to the previous version, pausing or cancelling in-flight reprocessing

Simulation Mode (Dry Run) Reporting

Given a published Policy Pack version When I run Simulation Mode against a selected cohort (program, date range, or submission IDs) Then the system produces a non-invasive report listing would-be redactions per submission, field/file, category, strategy, and confidence And no changes are made to stored artifacts or reviewer views And the report is downloadable as CSV and JSON and viewable in-app with filters And the simulation respects the pack’s current mappings, thresholds, redaction styles, and language scopes

Pre-Review Redaction Pipeline

"As a reviewer, I want submissions to be automatically redacted before I see them so that I can score fairly without exposure to identifying information."

Description

Implement a scalable, idempotent redaction pipeline that runs on submission ingest and prior to reviewer access, ensuring reviewers only see content compliant with the selected policy pack. Maintain a secure original copy and a redacted derivative for each artifact, with lineage linking and integrity hashing to prove no content tampering. Support streaming redaction for large files, delta updates when submissions are edited, and automatic reprocessing when a pack version changes. Preserve necessary hashed identifiers to keep conflict-of-interest checks and eligibility rules functioning without exposing raw PII. Provide UI indicators for reviewers showing where redactions occurred without revealing content. Integrate with the rubric builder to ensure scoring fields remain available post-redaction. Provide performance SLAs (e.g., P95 under 5 seconds for typical submissions) and retry/queueing for peak loads.

Acceptance Criteria

Submission Ingest Redaction Gate

Given a new submission with a selected policy pack When the submission is ingested Then the pipeline creates an encrypted original and a redacted derivative, links them with lineage IDs, and stores SHA-256 hashes for both. Given the same submission and policy pack are reprocessed without changes When the pipeline runs again Then outputs are identical, no duplicate artifacts are created, and hashes match previous values (idempotent). Given a submission awaiting redaction When a reviewer attempts access Then access to any artifact is blocked until redaction completes. Given redaction has completed When a reviewer accesses the submission Then only the redacted derivative is discoverable and downloadable via UI and API.

Reviewer Experience Compliance

Given a reviewer is assigned to a submission When they request artifacts via UI or API Then only redacted derivatives are returned; any attempt to access originals returns HTTP 403 and is audit-logged with user, time, and artifact ID. Given redacted content is displayed in the viewer When redactions are present Then placeholders appear at the exact locations with category labels from the policy pack; no raw content is retrievable via copy, print, thumbnail, export, or alt-text. Given a rubric references fields affected by redaction When the reviewer opens the scoring form Then all rubric fields remain present and enterable; redacted inputs show safe surrogates (e.g., "(redacted)" or hashed IDs) without validation errors. Given WCAG 2.1 AA requirements When viewing redaction indicators Then indicators are screen-reader accessible and meet contrast ratio >= 4.5:1.

Streaming Redaction for Large Artifacts

Given an upload >= 500 MB or > 500 pages When redaction runs Then processing uses streaming/chunked I/O with peak memory per worker <= 200 MB and completes without timeouts. Given a 1 GB PDF test corpus When processed Then P95 end-to-end redaction time <= 120 seconds and lineage plus integrity hashes are produced. Given a network interruption during streaming When the connection resumes within 5 minutes Then the job continues from the last confirmed chunk without restarting from the beginning.

Delta Update Reprocessing

Given an applicant edits a small text field (<= 10 KB) in an already-ingested submission When saved Then only affected sections are reprocessed; P95 redaction completion <= 2 seconds; derivative version increments and lineage records the delta. Given edited content intersects redaction rules When reprocessed Then reviewer-facing redaction indicators update and an "Updated" badge appears on the artifact within 1 minute. Given no relevant changes to redaction scope When reprocessed Then no new derivative is created and hashes remain unchanged.

Policy Pack Version Change Auto-Reprocess

Given a policy pack is versioned from Vx to Vy When published Then all submissions tagged with the pack are enqueued for reprocessing within 5 minutes and marked "stale" until completion. Given reprocessing succeeds When complete Then stale flags clear; new derivative versions and hashes are recorded; prior derivatives remain immutable for audit. Given transient processor failures When they occur Then the system retries with exponential backoff up to 5 attempts; failures route to a dead-letter queue with alerts to Ops within 10 minutes.

Hashed Identifiers Preserve COI and Eligibility

Given PII fields required for COI/eligibility (e.g., email, institution) When redacted Then fields are replaced by tenant-scoped, salted SHA-256 hashes; salts are rotated quarterly without breaking in-cycle comparisons. Given a gold-standard dataset with raw PII decisions When processed via hashed identifiers Then COI and eligibility outcomes achieve >= 99.9% parity; any mismatches are logged with anonymized diff reasons. Given reviewer-visible payloads and logs When inspected Then no raw PII values are present; only hashed tokens and category labels are exposed.

Performance, Queueing, and Observability SLAs

Given a typical submission (<= 25 MB total, <= 100 pages, <= 10 attachments) When ingested Then P95 time from upload complete to redacted-ready <= 5 seconds and P99 <= 10 seconds, measured over a rolling 30-day window. Given peak load of 10,000 submissions per hour When occurring Then the system maintains the above P95 for typical submissions; queue depth, wait time, and success rate are exported as metrics; monthly redaction success rate >= 99.95%. Given job failures or SLA breach When detected Then alerts fire within 2 minutes with runbook links; operators can replay jobs from the queue without data loss.

Retention & Auto-Purge Scheduler

"As a data steward, I want automated retention enforcement driven by policy packs so that we meet regulatory obligations without manual cleanup work."

Description

Allow policy packs to define retention windows by data class (submission content, reviewer notes, applicant identifiers, audit logs), with actions at expiry (purge, anonymize, archive) and optional grace periods. Provide legal hold controls to pause purges with justification and approval. Implement a scheduler that reliably executes retention actions, including deletion in primary storage and coordinated purge from backups and search indexes. Notify data owners ahead of purge events and record immutable audit entries for all retention decisions and outcomes. Support event-based retention (e.g., retain N days post-decision) and configurable exceptions per program where permitted. Surface dashboards and reports showing upcoming purges, exceptions, and completion status.

Acceptance Criteria

Per-Data-Class Retention Rules and Actions with Grace Periods

Given an admin defines in a policy pack: Submission content 365 days then purge (grace 14 days); Reviewer notes 730 days then anonymize (grace 7 days); Applicant identifiers 180 days then anonymize (no grace); Audit logs 2555 days then archive (grace 30 days) When the policy pack is saved and applied to Program A Then the system validates allowed action types per data class and rejects invalid combinations with clear errors And the rules are persisted and visible in the policy pack summary And expiry and grace dates are computed for all existing records by data class within 5 minutes And new records in Program A receive expiry metadata at creation time And an immutable audit entry captures the rule set, author, timestamp, and affected scope

Event-Based Retention Anchored Post-Decision

Given an application receives a final decision at 2025-09-01T12:00Z When a rule "retain submission content for 90 days post-decision" applies Then the system sets the expiry to 2025-11-30T12:00Z and stores the anchor event reference And if the decision timestamp changes, the expiry is recomputed within 5 minutes and an immutable audit entry records before/after And if no decision exists, the record is marked "awaiting anchor" and is excluded from purge scheduling And if the decision is rescinded, the expiry is cleared and the change is audited

Legal Hold Pauses Purge with Justification and Approval

Given a record is scheduled for a retention action within 7 days When a compliance officer requests a legal hold with a justification of at least 20 characters and a named approver approves it Then the item status changes to "On Hold" immediately and no retention actions execute while the hold is active And the approver must be different from the requester; the system enforces two-person control And an immutable audit entry captures requestor, approver, justification, timestamps, and affected items And notifications are sent to the data owner(s) and compliance list within 5 minutes And when the hold is released with a reason, the next eligible purge date is recalculated and audited

Scheduler Reliability and Coordinated Purge Across Stores

Given items reach their expiry after any grace period When the scheduler runs Then delete actions remove data from primary storage within 1 hour and confirm purge requests to backup and search index stores And anonymize actions irreversibly remove direct identifiers while preserving configured non-PII fields within 1 hour And archive actions move data to designated cold storage with retrieval metadata within 1 hour And all tasks are idempotent; reruns do not duplicate effects or corrupt state And transient failures are retried up to 5 times with exponential backoff; terminal failures are marked Failed and alerted And a single immutable audit record per item summarizes action type, stores touched, outcome, and timestamps

Advance Notifications to Data Owners Ahead of Purge

Given a policy pack sets "notify 7 days before retention action" When items are scheduled for action in 7 days Then email and in-app notifications are sent to each program's data owner with counts by data class and links to review And a 24-hour reminder is sent if the action remains scheduled and no legal hold was applied And notification deliveries and failures are logged; bounces appear in an admin report And links only expose items within the recipient's program(s) based on permissions

Dashboards and Reports for Upcoming Purges and Completion

Given a user with Retention Admin role opens the Retention dashboard When viewing the default Next 30 Days window Then the dashboard shows totals by program and data class for scheduled actions, active holds, and exceptions And filters allow Program, Data Class, Action Type, and Status (Scheduled, On Hold, In Progress, Completed, Failed) And clicking a metric drills to item lists with CSV export and links to audit entries And a Last 90 Days widget shows counts and success rate for purge/anonymize/archive with a trend line And dashboard queries return within 3 seconds for up to 100k records

Program-Level Exceptions Within Policy Boundaries

Given a global policy pack defines default retention and bounds (e.g., submission content min 90 days, max 365 days) When Program B requests an exception to 270 days for submission content and disables anonymization for reviewer notes where permitted Then the system validates the exception is within bounds and allowed for the data class; invalid exceptions are blocked with error feedback And approved exceptions apply only to Program B and trigger expiry recomputation for affected items within 10 minutes And immutable audit entries capture creator, rationale, before/after values, and effective date And changing or removing the exception recalculates expiries and records an audit entry

Role-Based Controls & Justified Overrides

"As a program manager, I want controlled overrides with approvals and audit trails so that I can handle exceptional cases without compromising compliance."

Description

Introduce fine-grained permissions to apply, edit, and override policy packs at the organization, program, and submission levels. Default behavior is one-click application of a pack to a program; any deviation (e.g., unredacting a specific field for an appeal) requires a time-bound override with justification, optional approver workflow, and automatic reversion. Provide guardrails to prevent disabling critical categories mandated by the selected standard, with clear warnings and links to policy rationale. All overrides are fully audited and visible in a policy drift report. Integrate notifications to compliance owners when overrides occur or approvals are pending.

Acceptance Criteria

Apply Pack to Program — Authorized Roles Only

Given a user with Apply Pack permission on a program selects a Policy Pack and clicks Apply, When the user confirms, Then the pack is applied to the program within 2 seconds and default settings are enforced. Given a user without Apply Pack permission attempts to apply or change a pack, When they click Apply, Then the action is blocked and a permission error message is shown with the required role listed. Given a program already has a pack, When a different pack is applied, Then the previous pack is replaced, affected settings are recalculated, and the change is logged with user, timestamp, old pack, new pack. Given the pack application completes, When reviewers access submissions in that program, Then redaction rules from the selected pack are enforced immediately on subsequent page loads.

Field-Level Unredaction with Time-Bound Justified Override

Given a redacted field on a specific submission, When an authorized user initiates an Unredact action, Then the system requires a justification text (min 10 characters) and a time-bound expiry (date-time) before enabling Save. Given an override form, When the user sets an expiry beyond the organization’s configured maximum TTL, Then the Save button remains disabled and an error states the allowed maximum. Given an override is saved, When the override activates, Then only the scoped field(s) and submission(s) become visible to the permitted roles, and a visible banner indicates an active override with expiry countdown. Given an override is active, When any user without View-Unredacted permission attempts to access the field, Then the value remains redacted and the access attempt is logged. Given an override is created, When saved, Then the event is recorded with user, role, justification, scope, start time, expiry, and affected fields.

Guardrails Prevent Disabling Mandated Categories

Given a Policy Pack aligned to a standard (e.g., GDPR, FERPA), When a user attempts to disable a category flagged as Mandated by the standard, Then the toggle is disabled and a warning tooltip explains the mandate. Given a guardrail warning, When the user clicks View policy rationale, Then a rationale panel opens with the governing clause reference and link to the policy document. Given mandated categories exist, When a user needs visibility for an appeal, Then the system directs the user to create a time-bound override instead of editing the base pack. Given a guardrail is triggered, When the user attempts to save changes, Then the save is blocked and an inline error lists each mandated category causing the block.

Optional Approval Workflow for Overrides

Given the organization has Override Approval enabled for the program, When a user submits an override, Then its status becomes Pending and it is not active until approved by a designated approver. Given a pending override, When an approver reviews it, Then they can Approve or Reject with a required comment (min 5 characters), and the decision is timestamped and attributed. Given an override is approved, When the decision is recorded, Then the override activates immediately and the activity log captures approver, decision, comment, and activation time. Given an override is rejected, When the decision is recorded, Then the override remains inactive and the requester is informed with the rejection comment. Given approvals are disabled for the program, When a user submits an override, Then it activates immediately without requiring approval and is logged as No approval required.

Automatic Reversion and Scope Restoration on Override Expiry

Given an active override with an expiry, When the system time reaches the expiry, Then the override automatically deactivates and the original pack redactions are reinstated within 5 minutes. Given an override is nearing expiry (24 hours prior), When the threshold is reached, Then the requester and compliance owners receive a reminder notification. Given an override is auto-reverted, When reversion occurs, Then an audit entry records the reversion time, actor=system, and the fields restored. Given a user with permission selects Revert Now, When they confirm, Then the override ends immediately and redactions are restored with a log entry for the manual reversion.

Audit Log and Policy Drift Report Visibility & Export

Given overrides and pack changes occur, When a compliance owner opens the Policy Drift report, Then they can view entries including program, submission, pack, fields affected, user, role, justification, start, expiry, approval decision, and reversion time. Given the drift report, When filters for date range, program, user, standard, and status are applied, Then results update within 1 second and match the selected filters. Given the drift report is open, When Export CSV is clicked, Then a CSV downloads containing all visible columns and applied filters, with immutable record identifiers. Given an audit entry exists, When a user tries to edit or delete it, Then the action is blocked and a message states that audit records are immutable.

Compliance Notifications for Overrides and Approvals

Given an override is submitted, When the request is created, Then compliance owners receive an in-app and email notification within 1 minute containing requester, program, submission, fields, justification excerpt, and required action. Given a pending override awaiting approval, When 24 hours elapse without action, Then a reminder notification is sent to approvers and the requester. Given an override is approved or rejected, When the decision is recorded, Then the requester and compliance owners are notified with the decision, comment, and effective time. Given an active override expires or is manually reverted, When the event occurs, Then the requester and compliance owners receive a completion notification and the linked audit entry can be opened from the message.

Compliance Audit & Evidence Exports

"As an auditor, I want comprehensive, exportable evidence of how policy packs were configured and enforced so that I can verify compliance quickly and reliably."

Description

Record tamper-evident logs for every policy action, including pack selection, version changes, taxonomy edits, detection results, redaction diffs, reviewer accesses, overrides, and retention events. Provide on-demand evidence exports per program or time range that include configuration snapshots, rule diffs, and event logs mapped to relevant regulatory articles (e.g., GDPR Art. 5, FERPA directory info handling). Exports are available in human-readable PDF and machine-readable JSON/CSV, with digital signatures and checksums for integrity verification. Include dashboards for compliance status, exceptions, and coverage across active programs, with APIs for SIEM ingestion and institutional record-keeping.

Acceptance Criteria

Tamper-Evident Audit Logging for Policy Actions

- Given any policy action (pack selection, version change, taxonomy edit, detection run, redaction change, reviewer access, override, retention event), When the action is committed, Then an audit entry is recorded with action type, actor ID, program ID, object ID, UTC ISO 8601 timestamp, before/after hashes, and correlation ID. - Given sequential audit entries for a program, When verification runs, Then each entry contains a SHA-256 hash pointer to the previous entry forming an immutable chain. - Given an attempt to modify or delete an audit entry, When chain verification runs, Then a tamper alert event is created within 60 seconds and surfaced on the Compliance Dashboard. - Given audit log query filters (action type, actor, time range), When a query for up to 10,000 entries is executed, Then results return within 2 seconds and are fully paginated.

On-Demand Evidence Export by Program and Time Range

- Given an authorized compliance admin, When requesting an export for a selected program and time range, Then the system produces a bundle within 2 minutes containing configuration snapshots, rule diffs, detection results, redaction diffs, reviewer access logs, overrides, and retention actions scoped to the selection. - Given an export is requested, When selecting output formats PDF and JSON/CSV, Then all formats contain identical records, counts, and mappings. - Given an export completes, When downloaded, Then filenames include program slug, date range, and export UUID; the PDF is human-readable and the JSON/CSV are machine-readable with documented schema version. - Given no matching data, When an export is generated, Then all sections render with zero counts and a statement of no applicable events.

Regulatory Article Mapping in Evidence Exports

- Given audit events and policy configurations, When generating an export, Then each relevant record includes mapped regulatory citations with IDs and short titles (e.g., GDPR Art.5.1(c), FERPA Directory Information). - Given an event without an applicable mapping, When included in the export, Then it is flagged as unmapped and listed in an Exceptions section with counts and percentage of total. - Given a policy pack version, When exported, Then the export includes the mapping table version and a diff from the prior version if available.

Digital Signatures and Checksum Verification

- Given an export is finalized, When generated, Then a detached digital signature using X.509 (RSA or ECDSA with SHA-256) and a checksum manifest of per-file SHA-256 hashes are included. - Given the verification endpoint or CLI, When provided the export artifact and manifest, Then verification returns Pass if signatures validate, certificates are within validity and not revoked as of export time, and all checksums match. - Given a modified export file, When verification runs, Then verification returns Fail and identifies the altered file(s). - Given certificate rotation occurs, When generating subsequent exports, Then each export embeds the certificate chain up to the configured root CA.

Compliance Dashboard: Status, Coverage, and Exceptions

- Given active programs, When opening the Compliance Dashboard, Then per-program tiles display status (Compliant, Exceptions, Attention), coverage %, last export time, and last verification result, refreshed at least every 5 minutes. - Given applied filters (program, date range, regulation), When filters are changed, Then charts and tables update within 2 seconds with consistent totals across widgets. - Given exceptions exist (unmapped events, overrides, failed verifications, tamper alerts), When viewing the Exceptions table, Then each row shows program, event ID, severity, owner, age, and recommended action, with bulk export to CSV.

SIEM Ingestion API for Audit Events

- Given a SIEM client with valid credentials, When subscribing via webhook or polling with a time-bounded cursor, Then audit events are delivered over HTTPS as NDJSON at ≥1,000 events/second sustained with back-pressure respected. - Given the published JSON schema, When events are ingested, Then each event includes schema_version, event_type, timestamps, actor, program, object, and hash pointer and passes schema validation; unknown fields are ignored by clients. - Given transient network failures, When retries occur, Then delivery resumes from the last acknowledged cursor without loss or duplication, with idempotency keys enforced for 24 hours. - Given security policies, When calling the API, Then mTLS and OAuth 2.0 client credentials with the audit.read scope are required; invalid certs or scopes return 401/403 and generate an audit event.

Multilingual Mask

Language-aware PII detection for 30+ languages and mixed-script content, including transliterated names and locale-specific formats for phones, addresses, and IDs. Reduces manual triage in global calls and supports equitable, international programs.

Requirements

Auto Language & Script Detection

"As a program manager, I want MeritFlow to automatically identify the languages used in each submission so that the correct PII rules are applied without manual triage."

Description

Automatically detect primary and secondary languages and scripts in applicant submissions, comments, and metadata in real time, including code‑mixed content and right‑to‑left scripts. Outputs per‑segment language/script tags that downstream PII detectors consume to apply correct locale models. Handles Unicode normalization, diacritics, and zero‑width characters to improve accuracy and prevent evasion. Integrates with MeritFlow’s ingestion pipeline and review workflows, exposing language tags via API and admin UI filters.

Acceptance Criteria

Real-time per-segment tagging in ingestion pipeline

Given a submission is ingested via API or UI with text split into segments up to 2KB When the ingestion pipeline processes each segment in real time Then a language tag (BCP 47) and a script tag (ISO 15924) with confidence [0,1] and byte offsets (start,end) are emitted per segment And p95 tagging latency is <= 150 ms per 2KB segment and p99 <= 300 ms under sustained load of 100 segments/s And no segments are dropped; failed attempts are retried up to 2 times; persistent failure yields error code DETECT-001 and the segment is marked untagged

Code-mixed primary/secondary language detection

Given a code-mixed segment where the secondary language constitutes >= 15% of tokens When the segment is processed Then the output includes both a primary and a secondary language tag with their scripts and confidences And for segments where the secondary share < 10% of tokens, no secondary tag is produced And on a labeled test set of 1,000 segments across 10 language pairs, primary language accuracy >= 95% and secondary-language presence detection F1 >= 0.85

Right-to-left scripts and mixed-direction content handling

Given segments written in Arabic or Hebrew with embedded left-to-right tokens (numbers, URLs, emails) When the segments are processed Then script is correctly identified as Arab/Hebr and language as ar/he with confidence >= 0.9 for clean samples And embedded LTR tokens do not change the primary language/script tag And on a benchmark of 200 RTL segments, misclassification rate is <= 2%

Unicode normalization and invisible character robustness

Given pairs of equivalent texts differing only by Unicode composition (NFC vs NFD) or insertion of zero-width characters (ZWJ, ZWNJ, ZWSP) When detection runs with normalization enabled Then resulting language/script tags and confidences differ by <= 0.01 between pairs And zero-width characters do not create extra segments or empty-language outputs And inputs containing only invisible characters yield language=und and script=Zyyy

Language/script tags exposed via public API

Given a submission with tagged segments exists When a client calls GET /v1/submissions/{id}/segments?fields=language,script,confidence,start,end Then HTTP 200 returns JSON where each segment includes language.bcp47, script.iso15924, confidence (0..1), start, end, updatedAt, modelVersion And filtering by language=ar and script=Arab returns only matching segments And invalid parameters yield HTTP 400 with error code AC-LANG-400; unknown submission yields 404; rate limiting yields 429 with Retry-After

Admin UI filtering by language and script

Given an admin opens the Submissions page When filters language=ar and script=Arab are applied Then the list updates within 500 ms for datasets <= 10,000 submissions And visible counts and results match the API for identical filters And selected filters persist after page reload and when sharing the URL And RTL language names render correctly and remain aligned in filter chips and results

Downstream PII model routing from language/script tags

Given the PII detection stage consumes segments with language/script tags When processing a mixed-language submission Then the PII detector selects locale-specific models per segment based on the tags and logs model_id plus tag used And on a routing validation set of 500 segments across 12 languages, routing accuracy is 100% whenever a supported tag exists And when language=und or tag is unsupported, the default model is used and event MERITFLOW.PII.ROUTING.FALLBACK is emitted

Cross‑Language PII Entity Recognition

"As a grant coordinator, I want reliable PII detection across languages so that applicants can be anonymized consistently for blind review."

Description

Detect and classify personally identifiable information across 30+ languages using language‑aware models and dictionaries, including names, emails, phone numbers, postal addresses, dates of birth, and national IDs. Supports mixed‑script text and locale conventions to minimize false positives and negatives. Provides entity types, spans, confidence scores, and normalization for downstream masking and auditing. Runs synchronously on form fields and asynchronously on long‑form text to meet portal SLAs.

Acceptance Criteria

Synchronous Field Detection SLA (30+ Languages)

Given a single form field input up to 1 KB containing text in any of the 30+ supported languages or containing no PII When the synchronous PII detection API is invoked Then a response is returned within 150 ms p95 and 300 ms p99 And detected entities include type, start_index, end_index (Unicode code point offsets), confidence in [0,1], and normalized_value And no entities are returned when the input contains no PII And results are deterministic for identical inputs with the same model_version within a session

Asynchronous Long-Form Processing with Callback

Given a text payload between 1 KB and 200 KB with multilingual and mixed-script content When it is submitted to the asynchronous endpoint with a callback URL Then a 202 Accepted with job_id is returned within 100 ms And the job completes within 2 minutes p95 and 5 minutes p99 And the result includes all detected entities with type, start_index, end_index (Unicode code point offsets), confidence, and normalized_value And the service supports idempotent submissions via idempotency_key and exposes job status transitions: queued -> processing -> succeeded/failed

Mixed-Script and Transliterated Name Recognition

Given a curated evaluation set containing mixed-script names (e.g., Latin+Cyrillic, Arabic+Latin) and transliterated variants across at least 10 language pairs When the detector runs with default thresholds Then PERSON entity precision ≥ 0.92 and recall ≥ 0.88 (F1 ≥ 0.90) on the evaluation set And cross-script homograph false positive rate ≤ 1.5% And normalized_value provides a script-consistent canonical form when derivable (e.g., transliteration mapping), else returns the original surface form

Locale-Specific Phones, Addresses, and National IDs

Given a test corpus spanning at least 20 locales with ground-truthed phones, postal addresses, and national IDs When detection and normalization are executed Then PHONE entities are validated and normalized to E.164 format where possible And ADDRESS entities are parsed into components (street, city, region, postal_code, country_code ISO 3166-1 alpha-2) where parseable, else returned as a single span with normalized_value preserving original formatting And NATIONAL_ID entities are recognized with pattern and checksum validation where applicable and normalized to a canonical pattern per country And per-entity precision ≥ 0.95 and recall ≥ 0.90 on the corpus And ambiguous address fragments (e.g., single numbers without context) are not labeled as ADDRESS (false positive rate ≤ 5%)

Span Accuracy and Unicode Normalization

Given inputs containing combining marks, surrogate pairs, emojis, and mixed normalization forms (NFC/NFD/NFKC/NFKD) When entities are detected Then start_index and end_index are reported as Unicode code point offsets relative to an NFC-normalized text snapshot And extracting spans using these offsets from the NFC snapshot reproduces the exact entity substring And span accuracy ≥ 99.5% on a Unicode edge-case test set with ground-truth offsets

Confidence Scores and Threshold Configurability

Given per-entity confidence thresholds are configurable via service settings When thresholds are increased for an entity type Then the number of returned entities for the same input monotonically decreases or remains equal; when thresholds are decreased, counts monotonically increase or remain equal And the default thresholds yield macro-averaged precision ≥ 0.93 and recall ≥ 0.90 across supported languages on the validation set And each response includes model_version and threshold_used for auditability

Transliteration‑Aware Name Matching

"As a reviewer operations lead, I want transliterated names to be detected and masked so that identity cues do not slip through in global applications."

Description

Identify personal names that appear in transliterated or romanized forms (e.g., Zhang San/张三, Mohammad/Muhamad, Müller/Mueller) by combining transliteration mappings, phonetic similarity, and script conversion. Flags likely self‑identifying references even when names are obfuscated or partially spelled. Integrates with conflict‑of‑interest and masking modules to ensure equitable treatment in international programs.

Acceptance Criteria

Chinese–English Transliteration Detection (张三 ↔ Zhang San)

Given a document containing both "张三" and "Zhang San" When the PII detector runs Then both occurrences are classified as Person Name and linked to a single canonical entity ID Given a labeled CN↔EN transliteration test set of ≥500 positive pairs with distractors When detection runs Then name-level recall ≥ 0.92 and precision ≥ 0.96 Given tone-less, spacing, and punctuation variants (e.g., "ZhangSan", "Zhang S.") When detection runs Then ≥90% of such variants are correctly matched to the Chinese source name Given a 1,000-character input When detection runs Then median latency ≤ 150 ms and p95 latency ≤ 300 ms per document

Arabic Name Variant Matching (Mohammad/Muhamad/Mohamed)

Given a reviewer name "Mohammad" and applicant text containing "Muhamad" When conflict checking runs Then a match is produced with similarity score ≥ 0.85 and flag reason "transliteration_match" Given a labeled Arabic transliteration set covering ≥10 common names with ≥800 positive pairs When detection runs Then recall ≥ 0.94 and precision ≥ 0.95 Given right-to-left Arabic mixed with Latin transliterations in the same line When detection runs Then detected spans have correct start/end offsets matching visual positions Given a negative corpus of non-name Arabic words and common tokens When detection runs Then false positive rate ≤ 2%

Diacritics and Umlaut Equivalence (Müller ↔ Mueller)

Given a document containing "Müller" and "Mueller" When the PII detector runs Then both are classified as Person Name and resolved to the same canonical entity ID Given a European diacritics test set (≥500 pairs, e.g., José/Jose, François/Francois) When detection runs Then recall ≥ 0.95 and precision ≥ 0.98 Given locale-insensitive case variants (e.g., "JOSE", "José") When normalization runs Then tokens normalize to an equivalent form for matching without increasing false positives above 2% on a negative set

Obfuscated and Partial Name Detection (e.g., M*ham*d, Zhang S.)

Given a known reviewer name "Mohammad Al Karim" and applicant text containing "M*ham*d A. K." or "Mohamd K." When self-identifying reference detection runs Then a potential self-identifying reference is flagged with confidence ≥ 0.80 Given an obfuscated-name test set (vowel drop, asterisks, inserted punctuation; ≥400 positives) When detection runs Then recall ≥ 0.85 and precision ≥ 0.93 Given single-token common surnames appearing alone (e.g., "Singh") When detection runs Then they are not flagged as self-identifying without corroborating context, yielding ≤1% false positive rate on negatives

Conflict-of-Interest Integration with Transliteration Matches

Given a reviewer profile name "Алексей Иванов" and an applicant name "Aleksei Ivanov" When assignment pre-check runs Then a conflict candidate is created with reason "name_transliteration_match" and the similarity score is exposed via API and UI Given a reviewer dismisses a transliteration-based conflict with justification When the action is saved Then the decision is logged with reviewer ID, timestamp, justification text, and the assignment is unblocked while the audit record remains immutable Given a batch of 1,000 applications with conflict checks enabled When processing completes Then added wall-clock time attributable to transliteration matching is ≤ 5% versus baseline conflict checks

Masking Module Redaction Consistency for Transliteration Variants

Given detected variants "张三", "Zhang San", and "Zhang S." When blind-review masking is applied Then all spans are redacted and replaced with the same placeholder token (e.g., [NAME_1]) consistently across HTML and PDF outputs Given a blinded review packet is generated When an automated scan searches for the detected name variants Then zero unmasked occurrences remain in the packet Given masking is applied When audit logs are produced Then logs include the redaction count, placeholder-to-entity mapping, and scripts encountered for the document

Locale‑Aware Format Parsing (Phones, Addresses, IDs)

"As an international program admin, I want locale‑specific formats to be recognized and standardized so that masking is accurate regardless of where applicants are from."

Description

Validate and normalize phone numbers, postal addresses, and government ID formats according to country and region rules, including varying lengths, prefixes, and check‑digits. Uses detected locale hints (language, country, text context) to select parsers and returns standardized representations for consistent masking and deduplication. Covers common ID types (e.g., national ID, passport, tax numbers) with extensible rules per program.

Acceptance Criteria

E.164 Normalization for Phone Numbers With Locale Hints

Given a phone number string and available locale hints (language, country, calling code) When the parser processes the input Then it selects a country-specific rule-set using the highest-confidence hint And if valid, it returns normalized_e164 starting with '+' followed by digits only, country_code (ISO 3166-1 alpha-2), normalized=true And if invalid, it returns normalized=false with error_code in [invalid_length, invalid_prefix, invalid_checksum, invalid_number] and error_message And any extension (e.g., x123, ext. 123) is isolated into an extension field and not included in normalized_e164 And Unicode digits from any script and full-width forms are converted to ASCII digits before validation

Country-Specific Address Parsing and Normalization

Given a free-form postal address string and locale hints When the address is parsed Then the output includes structured fields: street_line_1, street_line_2, house_number, locality, administrative_area, postal_code, country_code (ISO alpha-2) And required components and formats are validated per country rules (e.g., postal_code pattern, province/prefecture presence, ordering) And a canonical_single_line is produced using the locale's template while preserving diacritics And an ascii_rendering is produced that transliterates where appropriate without losing meaning And invalid or missing components set normalized=false and include field-level error_codes (e.g., postal_code_invalid, locality_missing) And normalized=true only if all mandatory validations for that country pass

Government ID Validation with Check-Digit Support

Given an ID string labeled with id_type in [national_id, tax_id, passport, vat_id] and locale hints When the ID is validated Then a country- and type-specific rule-set is selected And format, allowed characters, length, and check-digit algorithm (where applicable) are enforced And if valid, the system returns standardized_value (uppercase, separators removed), id_type, country_code, normalized=true And if invalid, it returns normalized=false with error_code in [invalid_length, invalid_charset, invalid_checksum, unsupported_type] And the implementation supports at minimum: BR.CPF (checksum), ES.DNI/NIF (checksum), IN.PAN (format), US.SSN (format-only), EU.VAT (checksum), and passport number format per locale rules

Locale Hint Resolution and Parser Selection

Given inputs containing PII and surrounding context (UI locale, user-declared country, address country tokens, phone calling codes, IP geolocation) When the system computes locale hints Then it assigns weights to each hint and computes a confidence score per candidate locale And it selects the parser rule-set for the highest-scoring locale when score >= 0.70 And if no candidate meets the threshold, it returns normalized=false with error_code=ambiguous_locale and includes candidate_locales with scores And the selected hints, scores, and final locale are included in metadata for auditability

Mixed-Script and Non-Latin Digit Normalization

Given inputs that may mix scripts (Latin, Cyrillic, Arabic, Devanagari, full-width) across phones, addresses, and IDs When normalization runs Then Unicode digits from any script are mapped to ASCII digits prior to validation And full-width characters are mapped to half-width equivalents And normalization preserves the original text in original_value and emits canonical ASCII where applicable in normalized_value And parsing tolerates mixed-script tokens within a single field without misclassification

Program-Level Extensibility for Custom ID Types

Given a program admin defines a new custom ID rule via configuration (pattern, length, optional checksum, country scope) When the configuration is loaded without code deployment Then the system recognizes the new id_type as custom:<name> and validates inputs accordingly And valid inputs return standardized_value and normalized=true; invalid inputs return normalized=false with specific error_codes defined by the rule And disabling or removing the rule reverts behavior to error_code=unsupported_type without affecting standard rule-sets And custom rules are namespaced per program and are not visible to other programs

Canonicalized Output for Consistent Masking and Deduplication

Given any entity (phone, address, id) that validates successfully When normalization completes Then the system emits canonical_value suitable for hashing and deduplication: - phone: E.164 without extension - address: concatenated normalized fields in stable order plus country_code - id: uppercase alphanumerics without separators And emits entity_key = SHA-256(canonical_value || ':' || entity_type || ':' || country_code) And masking operations use canonical_value to generate consistent tokens across locales And repeated runs with identical inputs produce identical canonical_value and entity_key

Configurable Masking Policies & Redaction Rules

"As a program admin, I want to configure how PII is masked per program so that we meet policy and equity goals without harming review quality."

Description

Allow administrators to define program‑level masking policies specifying which PII types to remove or obfuscate, masking style (e.g., full redaction, partial star‑out, token replacement), and confidence thresholds by language. Supports context‑preserving redaction for rubric‑critical fields and exception lists for allowed terms. Policies are versioned per program and applied consistently across submission, messaging, and export surfaces.

Acceptance Criteria

Per-Language Policy Definition & Masking Styles

- Given an admin in Program "Global Scholars", When they create a policy selecting PII types [person_name, email, phone, postal_address, national_id] with styles {person_name: partial_star, email: token, phone: full_redact, postal_address: partial_star, national_id: token} and confidence thresholds {en:0.85, es:0.80, ar:0.82}, Then the policy is saved as version 1 and becomes Active. - Given a detected email in English with confidence 0.86, When policy style is token, Then the email is replaced by "[EMAIL_TOKEN]" across all masked surfaces. - Given a detected phone in Spanish with confidence 0.79, When the threshold for es is 0.80, Then the phone is not masked. - Given a person_name "María López", When style is partial_star, Then output is "M*** L***" preserving first letters and diacritics. - Given a national_id detected with locale BR, When style is token, Then output is "[ID_TOKEN:BR]" with no original digits retained.

Consistent Application Across Submission, Messaging, and Export

- Given a submission answer containing PII, When the Active policy is applied, Then the reviewer view, applicant messaging thread, and CSV export display identical masked tokens/characters for the same substrings. - Given a message sent from the submission containing PII, When notifications are generated (email and in-app), Then masking is applied before the notification payload is queued and no unmasked PII is present. - Given an export job for Program "Global Scholars", When the export type is "Masked", Then no unmasked PII appears in the file and masked spans match those shown in the UI for the same records.

Context-Preserving Redaction for Rubric-Critical Fields

- Given the admin marks field "Project Context" as context-preserving with targets [person_name, organization_name, postal_address], When content is processed, Then PII spans are replaced with semantic tokens "[NAME]", "[ORG]", "[ADDRESS]" and non-PII text remains unchanged. - Given reviewers open a masked submission, When a rubric criterion references organization type, Then the sentence structure and word spacing are preserved (no collapsed punctuation) and tokens are readable placeholders. - Given the same field is included in masked exports, When exported, Then the same semantic tokens appear exactly as in the reviewer UI for the same records.

Exception List for Allowed Terms

- Given the admin adds allowed terms ["UNESCO", "São Paulo", "First Nations"] with case-insensitive matching, When content is processed, Then these exact terms are never masked even if matched by detectors. - Given the term "Jordan" is added with language scope en only, When the content language tag for the span is ar or the token is "Jordán", Then the exception does not apply and masking proceeds per policy. - Given the exception list is updated, When the policy is saved as a new version, Then a preview on a fixed test corpus shows zero masked instances of the allowed terms and the version records the exception changes.

Policy Versioning, Activation, and Rollback

- Given an Active policy v1, When the admin edits thresholds and saves, Then v2 is created with timestamp, author, and change summary and becomes Active; v1 remains immutable. - Given submissions processed under v1, When v2 becomes Active, Then stored masked artifacts retain v1 redactions until the admin triggers "Reprocess with Active Policy". - Given the admin rolls back to v1, When confirmed, Then v1 becomes Active, v2 is archived, and the audit log records who, when, and why.

Mixed-Script and Locale-Specific Formats Under Policy

- Given text "Zhang Wei (张伟) +55 11 91234-5678 CPF 123.456.789-09", When the Active policy sets phone=full_redact and national_id=token with thresholds {pt-BR:0.80, zh:0.83}, Then the Brazilian phone is fully redacted and the CPF is replaced by "[ID_TOKEN:BR]", and both names are masked per the name style across scripts. - Given a transliterated name "Mohammad Al-Sayed" with confidence 0.84 and threshold en:0.85, When name style is partial_star, Then no masking occurs; When the threshold is lowered to 0.80 in a new version, Then the output becomes "M******* A*-S****". - Given a paragraph with spans tagged zh and en, When per-language thresholds differ, Then each span’s confidence is compared to its own language threshold, not a document-level default.

Reviewer‑Safe Redaction Preview & Diff

"As a program manager, I want to preview and validate redactions before reviewers see them so that I can catch issues without delaying the cycle."

Description

Provide an admin preview that shows before and after redaction with inline highlights, per‑entity tooltips, and confidence values; include a diff view for policy changes to assess impact before publishing. Ensure reviewer views and exports automatically receive masked content with placeholders that preserve readability and layout. Expose per‑submission masking status and quick‑fix actions from the queue.

Acceptance Criteria

Admin Pre‑Publish Redaction Preview (Before/After)

Given I am an admin and open Redaction Preview for a submission containing English, Arabic (RTL), and transliterated content with names, phones, addresses, and IDs When the preview loads Then the view shows side-by-side Original (left) and Redacted (right) panes for the same page/section And all masked entities are inline-highlighted by type in both panes with distinct, accessible colors (WCAG contrast >= 3:1) And focusing/hovering a highlight shows a tooltip with entity type, detected locale/script, confidence as a percentage with one decimal, and masking rule ID And Tab/Shift+Tab moves focus to next/previous entity highlight; Enter opens tooltip; Esc closes it And the preview completes rendering within 3 seconds for submissions up to 2 MB text or 2000 detected entities And pagination and search stay synchronized between both panes

Policy Change Impact Diff View

Given I have an unpublished masking policy draft with changes (e.g., thresholds, enabled entity types, locale patterns) When I open Diff View and select a comparison scope of 100 submissions Then I see counts of Added, Removed, and Unchanged masks by entity type and total delta per submission And I can toggle between Baseline Policy vX and Draft Policy vY and filter by entity type and locale And side-by-side diffs highlight entities added in green and removed in red in context And the diff computation completes within 60 seconds for 100 submissions each under 50 pages or 2 MB text And publishing the draft requires explicit confirmation after viewing the diff; cancel leaves baseline active And I can roll back to Baseline vX at any time without data loss

Reviewer Views and Exports Receive Masked Content

Given I am a reviewer viewing application details, rubric forms, comments, and messages for a masked submission When the content is displayed or exported (PDF, DOCX, CSV) Then all PII entities are replaced with type-specific placeholders (e.g., [NAME], [PHONE], [ADDRESS], [ID]) consistently across UI and exports And placeholders preserve line breaks and table layout; PDF/DOCX exports show the same page count as original ±1 page and no clipped/overflow text And RTL text order is preserved in masked regions; mixed-script segments render without mojibake And attempts to view unredacted originals or toggle masking are blocked for reviewer roles, returning 403 and logging the attempt And exported files are watermarked “Redacted” and contain no original PII in file metadata or hidden layers

Queue Masking Status and Quick‑Fix Actions

Given I am an admin on the Submissions Queue When masking has run or is running for items in the queue Then each row displays masking status (Not Run, In Progress, Complete, Needs Review, Failed), entity counts masked, last run timestamp, and detected languages/scripts And I can filter by status, language, entity type, and confidence band; results update within 500 ms for up to 10,000 items And row-level quick fixes allow: Re-run Masking, Adjust Thresholds for this submission, Mark Entity as Safe/Mask, Retry Failed with error details And bulk actions allow Re-run Masking and Adjust Thresholds for up to 500 selected items with progress feedback And applying a quick fix triggers an immediate reprocess and updates status within 30 seconds or shows failure with actionable error

Mixed‑Script Redaction Rendering Fidelity

Given a submission contains mixed-script text (Latin, Cyrillic, Arabic RTL, Devanagari) and transliterated names with locale-specific phone, address, and ID formats When I view the Redaction Preview and Redacted output Then masked regions maintain original directionality (LTR/RTL), punctuation spacing, and paragraph line counts ±1 line per paragraph And placeholders adapt to script (e.g., bracket glyphs mirrored appropriately in RTL) and remain readable And no surrogate pair or combining character is split by a mask; grapheme clusters are preserved And copy/paste from redacted view yields only placeholders, never original PII

Tooltip Data Completeness and Accuracy

Given I hover or focus any highlighted masked entity in Preview When the tooltip appears Then it displays: Entity Type (e.g., Person Name), Detected Locale (e.g., fr-FR) and Script, Confidence (0.0–100.0%), Masking Rule/Pattern ID, and Source (Model vs Rule) And values are correct against the underlying detection payload for 100% of sampled entities And tooltips render within 150 ms and remain accessible via keyboard and screen readers with ARIA roles and labels

Audit Trail, Confidence Controls & Overrides

"As a compliance officer, I want a complete audit trail and granular overrides so that we can demonstrate due diligence and correct mistakes quickly."

Description

Record all PII detection and masking events with timestamps, actors, policy versions, model versions, entity spans, and rationales. Allow authorized users to adjust confidence thresholds and approve per‑entity overrides (unmask or re‑mask) with mandatory notes. Provide searchable logs and exportable reports for compliance and post‑mortems, and surface metrics (precision/recall proxies) to guide policy tuning.

Acceptance Criteria

Log Entry Completeness for Detection/Masking

Given a submission with detected PII across multiple languages and scripts When the system performs detection and masking Then a log entry is created per entity with fields: event_id, timestamp (ISO 8601 with timezone), program_id, submission_id, field_path, page/offset/span (start, end, length), entity_type, language_code (BCP‑47), script, detection_confidence (0.0–1.0), action (mask/unmask/re‑mask), actor (system/user_id), actor_role, rationale (rule_id or model_reason), policy_version_id, model_version_id, request_correlation_id And Then all required fields are non‑null and validated against schema And Then entries are immutable and append‑only And Then mixed‑script and transliterated entities log correct language/script values and spans

Role-Gated Confidence Threshold Adjustment

Given a user with role "Compliance Admin" When they update the global or policy‑scoped detection confidence threshold Then the UI enforces a range [0.0, 1.0] with step 0.01 and requires a mandatory justification note (min 15 chars) And Then the change is recorded with previous_value, new_value, actor_id, timestamp, scope (global/program/policy), policy_version_id, model_version_id, change_reason And Then the new threshold takes effect only for new detections after the change effective timestamp And Given a user without permission attempts the change Then the action is blocked and an audit log of the denied attempt is recorded

Per-Entity Override (Unmask/Re-mask) with Mandatory Notes

Given an authorized reviewer viewing a masked entity When they choose Unmask Then the system requires a mandatory note (min 15 chars), captures reason codes, and records an override log linked to the original detection event_id And Then the UI reflects the unmasked state only for authorized roles, preserving masking for other roles per access policy And Given an authorized reviewer chooses Re‑mask on an unmasked entity Then the same logging and note requirements apply, and the visible state updates accordingly And Then each override is reversible via a Revert action that restores the prior state and logs a new event with type revert

Searchable Audit Log with Filters and Performance

Given an authorized user on the Audit Log page When they filter by date range (UTC), actor, event_type, entity_type, language_code, program_id, submission_id, policy_version_id, model_version_id, and action (mask/unmask/re‑mask/threshold_change/access_denied) Then results reflect all matching records And Then free‑text search over rationale, notes, and field_path returns results containing case‑insensitive matches And Then pagination supports page_size up to 200 and returns total_count And Then for up to 100k records in scope, the first page response time is ≤ 2 seconds at p95 And Then users without access cannot view logs outside their program scope

Exportable Compliance Reports

Given an authorized user When they export Audit Logs for a date range Then the system generates CSV and JSON exports with columns/fields matching the log schema and includes a header with export_timestamp (UTC), requester_id, criteria, and record_count And Then exports include all override notes and reason codes, and mask/unmask states at time of event And Then files larger than 100 MB are streamed and downloadable within 60 seconds for datasets up to 1 million records And Then the export includes a SHA‑256 checksum and is retained for secure re‑download for 7 days And Given the user lacks permission Then export initiation is blocked and the attempt is logged

Metrics Dashboard for Precision/Recall Proxies

Given the Metrics view When a date range and scope are selected Then the dashboard shows: detection volume, mask rate, override rate (unmask and re‑mask), reviewer‑confirmed false positives (unmask events), reviewer‑confirmed false negatives (re‑mask events), and estimated precision/recall proxies computed from overrides And Then metrics are segmentable by language_code, entity_type, program, and policy_version And Then counts match underlying audit events within 0.1% for the selected range And Then the dashboard updates daily at 00:30 UTC and on‑demand recompute for ≤ 90 days lookback completes within 5 minutes And Then metric definitions and computation version are displayed with model_version_id

Version Traceability and Replay

Given a submission with associated detection events When a policy or model version changes Then new events include the new version identifiers while historical log entries remain unchanged And Then authorized users can replay detection on the submission with a selected policy/model version in a staging mode, producing a comparison report of entity differences without altering production logs And Then the replay action and report generation are logged with actor_id, versions used, and timestamps

ReID Guard

Pre-publish scanner for reviewer comments, attachments, and admin notes that flags and auto-masks newly introduced PII. Stops accidental re-identification before feedback or decisions are shared with applicants or sponsors.

Requirements

Real-time PII Detection and Auto-Masking Engine

"As a program manager, I want reviewer feedback automatically scanned and masked for PII before it’s shared so that applicants and sponsors cannot be re-identified accidentally."

Description

A server-side scanning service that evaluates reviewer comments, admin notes, and decision text pre-publication to detect personally identifiable information (PII) using a combination of pattern matching (emails, phone numbers, national ID formats, student IDs), named-entity recognition for people and organizations, and contextual checks against application metadata (e.g., applicant names). Upon detection, the system replaces sensitive tokens with standardized masks (e.g., [EMAIL], [NAME]) in all outbound artifacts while preserving originals in a secure, access-controlled store. Supports configurable confidence thresholds, category toggles, deterministic masking for reproducibility, version-aware rescans, and multilingual extensibility (initially English). Exposes events and APIs for workflow integration and monitoring.

Acceptance Criteria

Pre-Publication Detection and Masking of Emails and Phone Numbers

- Given a reviewer comment <= 10 KB containing one or more email addresses and US-format phone numbers, When the pre-publication scan runs, Then all emails are replaced with [EMAIL] and all phone numbers with [PHONE] in the masked output, and the originals are preserved in the secure store linked to the scan record. - Given the same input, When the scan completes, Then the masked output contains no unmasked email/phone patterns (regex verification passes) and the count of masked tokens equals the count of detections returned by the engine. - Given a 10 KB comment, When scanned under nominal load, Then p95 end-to-end scan latency <= 500 ms and p99 <= 900 ms.

Contextual Name Detection Against Application Metadata

- Given application metadata with applicant and co-investigator full names and known aliases, When the comment contains exact or tokenized matches (e.g., first/last name, honorific + last name), Then those spans are masked as [NAME] and the mask count is recorded. - Given a substring that is part of another word (e.g., "domainamina"), When the scan runs, Then it is not masked as [NAME]. - Given a proper noun matching a person that is not present in metadata and has NER confidence < configured threshold, When the scan runs, Then it is not masked.

Deterministic Masking Reproducibility

- Given identical input text and identical configuration, When scanned multiple times, Then the masked output strings are byte-identical and their SHA-256 hashes are equal. - Given the same sensitive token appears multiple times in a single artifact, When scanned, Then each occurrence is masked with the same standardized placeholder (e.g., [EMAIL], [NAME]) and the occurrence count is consistent across runs. - Given two scans of an unchanged artifact version, When comparing results, Then the offsets and mask map are identical.

Category Toggles and Confidence Threshold Control

- Given category toggles for email, phone, national_id, student_id, person_name, organization_name, When a category is disabled, Then no detections or masks from that category appear in the results. - Given a confidence threshold set to 0.85, When the scan runs, Then only detections with confidence >= 0.85 are masked and counted. - Given NER language set to English, When the text is non-English (e.g., French), Then only pattern-based categories (email, phone, IDs) are applied and NER-based categories are skipped. - Given a configuration change, When a scan completes, Then the applied configuration (toggles, thresholds, language) is persisted with the scan record and exposed via API/events.

Version-Aware Rescan on Edited Content

- Given a comment v1 has been scanned, When the comment is edited to create v2, Then v2 is rescanned and linked to v1 via previous_version_id. - Given unchanged segments between v1 and v2, When comparing results, Then their mask decisions and offsets remain unchanged. - Given a token removed in v2, When rescanned, Then it no longer appears in v2 masked output or counts; given a new token introduced in v2, Then it is detected and masked per current configuration. - Given an edit triggers rescan, When rescanned, Then the audit log records editor, timestamp, old/new version IDs, and scan outcomes.

Scan Events and Monitoring/API Integration

- Given a scan is initiated, When processing starts, Then an event reid.guard.scan.started is emitted with submission_id, artifact_type, artifact_id, version, config_id, and timestamp. - Given a scan completes successfully, When emitting events, Then reid.guard.scan.completed is sent with scan_id, status=success, category_counts, masked_preview (first 200 chars), latency_ms, and checksum; on failure, status=failure with error_code and retryable flag. - Given the REST endpoint POST /api/reid-guard/scan, When called with text, config_id, and metadata, Then it returns 201 with scan_id immediately and the masked result is retrievable via GET /api/reid-guard/scans/{scan_id} within the defined SLO. - Given webhooks are configured, When a scan completes, Then the webhook receives the completed event with at-least-once delivery and exponential backoff retries for up to 24 hours.

Outbound Masking and Secure Original Access Controls

- Given masked content, When generating applicant portal views, reviewer feedback emails, sponsor PDFs, and CSV exports, Then all PII spans are masked consistently and no originals appear in any outbound artifact. - Given a rescan updates masks, When outbound artifacts are regenerated, Then caches are invalidated and new artifacts reflect updated masks within 60 seconds. - Given originals are preserved, When a user without the "View Original PII" permission accesses an artifact, Then they can only view the masked version; when a user with the permission views the original, Then access is logged with user_id, timestamp, artifact_id, and reason. - Given data-at-rest policies, When originals are stored, Then they are encrypted with AES-256 and accessible only to roles explicitly granted access via RBAC.

Pre-Publish Gate and Resolution UI

"As a grant coordinator, I want a clear pre-publish screen to review and resolve PII flags so that I can confidently release feedback without leaks."

Description

A blocking checkpoint integrated into the Publish Feedback/Decisions flow that aggregates all detected PII across comments and attachments, displays inline highlighted instances with severity levels, and offers resolution actions (approve mask, edit text, add exception, reclassify). Provides a live masked preview of recipient-facing output, bulk operations for multi-item resolution, and role-based overrides requiring justification. Prevents publication when high-severity items remain unresolved, triggers automatic rescans upon edits, and records all actions for audit. Fully aligns with MeritFlow’s workflow events and notifications.

Acceptance Criteria

Block Publish When High-Severity PII Unresolved

Given a user in the Publish Feedback or Publish Decisions flow with at least one unresolved High-severity PII instance detected across comments or attachments, When the user clicks Publish, Then the system blocks publication and displays a blocking banner listing the count of unresolved High-severity items. Given all High-severity PII instances are resolved via mask approval, edit-and-rescan, exception, or role-approved override, When the user clicks Publish, Then publication proceeds without block. Given unresolved Medium/Low items remain but no High-severity items remain, When the user clicks Publish, Then publication is allowed and the system displays a non-blocking warning summarizing remaining items. Given a block occurs, When the user expands the banner, Then the system deep-links to the unresolved items list filtered by High severity. Given publication proceeds, When the system emits workflow events, Then gate completion is recorded and standard MeritFlow workflow events and notifications are fired in the correct order.

Inline Highlighting with Severity and Source Context

Given the pre-publish gate opens, When detections are loaded, Then each PII instance displays inline highlight in its source context with severity label (High/Medium/Low), detector type, and confidence score. Given an instance originates from a comment, When the user clicks it in the list, Then the UI scrolls to the comment with the exact text span highlighted. Given an instance originates from a file attachment, When the user clicks it, Then the UI opens an attachment preview to the correct page/region with the span highlighted and shows filename and page number. Given detections are aggregated, When the list renders, Then duplicates across identical content are de-duplicated and grouped with a count of occurrences. Given more than 200 detections, When the list renders, Then it paginates or virtually scrolls without UI latency exceeding 500ms per interaction.

Resolution Actions and Comprehensive Audit Logging

Given a PII instance is selected, When the user chooses Approve Mask, Then the instance state changes to Masked and the masked token appears in preview. Given a user edits text to remove PII and saves, When the system rescans, Then the instance is marked Resolved by Edit if no longer detected. Given the user adds an Exception, When saving, Then a mandatory justification (min 20 characters) is required and stored. Given the user reclassifies severity, When saving, Then a role check is performed and justification is required; the displayed severity updates immediately. Given any resolution action is executed, When saved, Then an immutable audit record is created with user, timestamp, action type, instance id, old state, new state, justification (if any), and before/after redacted snippets.

Live Masked Preview Fidelity Across Outputs

Given masks are approved, When the user opens the recipient-facing preview, Then all masked tokens are replaced with a standard mask token (e.g., [REDACTED]) and are not selectable or copyable as original PII. Given no masks are applied, When the preview opens, Then detected PII remains highlighted but not masked until resolved. Given the user toggles between Applicant and Sponsor preview variants, When switching, Then masking is applied consistently across both variants. Given the user exports or sends a test email from preview, When the file/email is generated, Then the output matches the on-screen preview and contains no unmasked High-severity PII. Given the preview is refreshed after edits, When rescans complete, Then the preview updates within 2 seconds to reflect latest mask states.

Bulk Resolution at Scale

Given the user multi-selects PII instances across sources, When Approve Mask is applied in bulk, Then all selected instances transition to Masked with a single confirmation step and individual audit entries are created. Given the selection includes mixed severities, When bulk Add Exception is applied, Then a single justification is entered and copied to each item's audit; items requiring higher role are skipped with a clear error summary. Given more than 500 instances are selected, When a bulk action runs, Then the operation completes or streams progress with no client freeze and provides a completion summary with counts of success, skipped, and failed items. Given a bulk action completes, When the user clicks Undo (available for 5 minutes), Then the system reverts the affected items to prior states and logs the reversal in audit.

Role-Based Override and Justification Workflow

Given unresolved High-severity items remain, When a user without Override permission attempts to bypass the gate, Then the Override option is hidden or disabled. Given unresolved High-severity items remain, When a user with Override permission selects Override to Publish, Then a mandatory justification (min 50 characters) is required and the publish button is disabled until entered. Given an override publish is confirmed, When the system proceeds, Then an audit record is created capturing the override, justification, user role, and affected instances; and notifications are sent to the program’s compliance recipients. Given role permissions are changed in MeritFlow, When the gate loads, Then the Override option availability reflects the current role configuration without requiring a page reload.

Automatic Rescan and State Refresh on Edits

Given the user modifies a comment or uploads/replaces an attachment within the gate, When the edit is saved, Then an automatic rescan starts within 1 second and shows progress. Given a rescan is running, When the user attempts to publish, Then the publish control is disabled and a message indicates scanning is in progress. Given rescanning completes, When results differ, Then new detections are added, resolved detections are retired with a link to historical audit, and counts and blocks update accordingly. Given the detector service is unavailable, When a rescan is triggered, Then the system surfaces a retriable error, disables publish for High-severity uncertainty, and logs the outage event.

Attachment and Image Redaction with OCR

"As a reviewer, I want any PII in attached files to be automatically redacted in the versions sent to applicants so that sensitive details aren’t exposed."

Description

PII detection and redaction for reviewer-uploaded attachments (PDF, DOCX, images). Performs robust text extraction, including OCR for scanned documents and images, then locates PII and applies permanent vector/raster redaction overlays to the shareable copies while retaining originals in a restricted repository. Supports batch processing for bulk exports, progress indicators, file size/type constraints with graceful fallbacks, and consistent masking tokens across modalities. Ensures only redacted versions are accessible to applicants and sponsors via the portal or downloads.

Acceptance Criteria

OCR PII Detection Across Attachments

Given PII categories are configured and a reviewer uploads a mix of PDF (native and scanned), DOCX, and JPG/PNG files containing instances of those PII categories When ReID Guard processes the files Then text is extracted from all files, including OCR of images and scanned pages, with page and bounding-box coordinates captured for each token And all occurrences of the configured PII categories are detected and stored with file ID, page number, and coordinates And on the program’s validation corpus, detection achieves F1 >= 0.90 for each PII category and false-positive rate <= 2% overall And detection handles rotations (0°, 90°, 180°, 270°) and mixed orientations without manual intervention

Permanent Redaction Overlays on Shareable Copies

Given detected PII locations in an attachment When a redacted shareable copy is generated Then the copy contains permanent redactions: for PDFs, content streams under redaction bounds are removed or replaced and vector redaction rectangles are burned-in; for raster outputs, pixels within bounds are irreversibly replaced And copying text from redacted regions yields no original text And running OCR on the redacted copy returns masking tokens, not original PII And removing annotations or layers in common editors does not reveal original content And the original unredacted file remains unchanged

Originals Retained in Restricted Repository with Audit Trail

Given a file is processed by ReID Guard When storage actions are executed Then the original file is stored in a restricted repository with encryption at rest and access limited to roles with the "View Originals" permission And all access attempts (success and denial) are logged with user, timestamp, file ID, action, and outcome in an immutable audit trail And applicants and sponsors cannot access originals via UI or direct URL (returns 403/404) And redacted copies are stored separately and linked via version metadata to the original

Batch Redaction for Bulk Exports with Progress and Retry

Given an admin selects a batch of N attachments for redacted export When the batch job starts Then a progress UI displays total, processed, succeeded, failed, and ETA, updating at least every 2 seconds And files are processed concurrently up to the configured concurrency limit without crashing on single-file failures And successful files become available for download as soon as ready; failed files show actionable error codes and can be retried individually or in bulk And canceling the job stops new work, preserves completed outputs, and marks in-flight items as canceled And a paused or failed batch can be resumed without reprocessing already completed items

File Size/Type Constraints and Graceful Fallbacks

Given system-configured limits are displayed in the UI (supported types, max file size, max pages) When a file exceeds a limit or is of an unsupported type Then the user sees a clear inline error indicating the specific limit violated while other files continue processing And if a file exceeds a limit by <= 50%, the system attempts a fallback (page-wise rasterization + re-OCR) and proceeds with redaction; if > 50%, it is skipped with a distinct error code And timeouts trigger up to 3 retries with exponential backoff; after 3 failed attempts the item is marked Failed with a persistent message And all fallback and skip decisions are recorded in the batch report and audit log

Portal Access Restriction to Redacted Versions

Given a submission with both original and redacted attachments When an applicant or sponsor views or downloads attachments in the portal Then only redacted versions are listed and served via time-bound signed URLs; direct requests to originals return 403 And previews/thumbnails are generated exclusively from redacted versions And access control is enforced by role across API and UI, with attempts to access originals logged in the audit trail

Consistent Masking Tokens Across Modalities

Given a configured PII category-to-token map (e.g., EMAIL -> "[REDACTED: EMAIL]") When redaction is applied to reviewer comments, PDFs/DOCX, and images Then the same token text and visual style (font, color, opacity) are applied consistently across modalities and file types And multiple occurrences of the same PII value across files are replaced with the same category token without emitting any unique value-derived identifiers And token configuration is program-level and changes take effect on subsequent redactions while preserving tokens in already generated copies

Custom Rule Builder and PII Taxonomy Management

"As a compliance officer, I want to tailor PII detection rules to our program so that the scanner aligns with our policies and reduces false positives."

Description

An administrative interface to tailor detection scope per program, including enabling/disabling PII categories, defining custom regex patterns, uploading dictionaries (e.g., faculty or department names), setting severities, and managing exceptions/whitelists (e.g., permitted public award titles). Provides a test sandbox for sample text, rule versioning with change history, safe validation to prevent malformed patterns, and real-time configuration propagation to the scanning engine via a config service. Supports inheritance from global defaults with program-level overrides.

Acceptance Criteria

Program-Level Overrides of Global PII Taxonomy

- Given global PII categories are enabled by default, When an admin disables categories A and C and enables category D for Program X and saves, Then Program X configuration shows A and C disabled and D enabled, and production scans for Program X flag only enabled categories while other programs remain on global defaults. - Given Program X has overrides, When the admin selects Inherit from Global and saves, Then Program X reverts to global settings and override indicators are removed. - Given overrides were saved, When the admin reloads settings or returns later, Then the overrides persist and an audit log entry records who changed what and when.

Safe Validation for Custom Regex Rules

- Given an admin enters a new regex and clicks Save, When the pattern has syntax errors, Then the system rejects it with a clear error message pinpointing the failing segment and prevents saving. - Given a regex compiles, When validated against sandboxed inputs including a 10,000-character adversarial string, Then evaluation time is capped (<=100 ms per test) and patterns exceeding the cap are rejected with a performance warning. - Given a regex passes validation, When saved, Then it is stored with a unique rule ID, associated severity, scope (global/program), and Draft status, and is not used in production until Published.

Dictionary Upload and Matching

- Given an admin uploads a UTF-8 CSV or TXT dictionary with up to 50,000 entries containing duplicates and mixed case, When import completes, Then the system deduplicates, normalizes whitespace per entry, applies the chosen case-sensitivity setting, and shows an import summary (#added, #duplicates, #invalid) without errors. - Given the dictionary is enabled for Program X, When scanning sandbox text and production submissions, Then occurrences of dictionary terms are detected according to word-boundary and case rules and are attributed to the configured rule and severity. - Given a dictionary replacement is uploaded and confirmed, When publishing, Then the new dictionary becomes active without downtime and the prior dictionary is archived with version and timestamp.

Severity Levels Drive Masking and Publication Gates

- Given a rule with severity High triggers, Then the detection is auto-masked in previews and blocks publication until resolved or whitelisted. - Given a rule with severity Medium triggers, Then the detection is flagged and requires reviewer acknowledgment before publication but is not auto-masked by default. - Given a rule with severity Low triggers, Then the detection is informational and does not block publication or auto-mask content. - Given a rule’s severity is changed and Published, Then subsequent scans reflect the new behavior and the change appears in the version history with author, timestamp, and diff.

Exceptions and Whitelists by Program and Rule Scope

- Given a whitelist entry "Nobel Prize in Chemistry" scoped to Program X is active, When scanning Program X content, Then matching text is not flagged by associated rules; When scanning other programs, Then the text is flagged normally. - Given a whitelist is attached to Rule R only, When scanning content that would trigger multiple rules, Then only Rule R is suppressed and other rules still trigger. - Given a whitelist entry is deactivated and the configuration Published, When rescanning the same content, Then previously suppressed detections reappear according to rule behavior.

Rule Versioning, Draft/Publish, Revert, and Audit

- Given pending config changes (regex, severity, whitelist) in Draft, When the admin clicks Publish, Then a new version number is created capturing author, timestamp, and a diff summary, and it becomes the active configuration. - Given Version N exists, When the admin selects Revert to Version N and confirms, Then Version N becomes active and a new version is recorded documenting the revert action and who performed it. - Given two admins edit concurrently, When one attempts to Publish over a stale Draft, Then the system blocks the publish with a conflict message and requires merge or refresh before proceeding.

Real-Time Propagation to Scanning Engine and Sandbox Consistency

- Given a program configuration is Published, When observed by the scanning engine, Then new scans use the new configuration within 30 seconds, and in-flight scans continue with their original configuration. - Given the sandbox is used for Program X, When the same text is scanned in sandbox and then in production after propagation, Then results match exactly for detections, severities, and masking previews. - Given a propagation failure occurs, When detected by the config service, Then it retries with exponential backoff and surfaces an "Out of Sync" alert in the admin UI until recovery, after which the alert clears automatically.

Audit Trail, Reporting, and Data Retention Controls

"As an administrator, I want a complete audit trail and reports on PII handling so that we can demonstrate due diligence and improve our process."

Description

Comprehensive logging of detections, user resolutions, overrides, publish outcomes, and system events with timestamps and actor attribution. Provides exportable reports and in-product dashboards showing volumes by category, resolution times, trends by program, and false-positive rates to guide tuning. Includes configurable retention policies for logs and unmasked originals with automated purge, role-based access controls for viewing/exporting data, and default-masked exports to minimize exposure during analysis.

Acceptance Criteria

Event Logging for Detections, Resolutions, Overrides, Publish, and System Events

Given ReID Guard scans reviewer comments, attachments, and admin notes When a PII detection, user resolution, override, publish action, or system error occurs Then an immutable audit record is written within 2 seconds containing event_id, timestamp (UTC ISO 8601), actor_id (user_id or "system"), program_id, application_id, artifact_type, event_type, detection_category (if applicable), rule_version, outcome, and correlation_id And the record is retrievable via UI and API by filtering on date range, program_id, event_type, and actor_id And audit records persist across service restarts and are retained per the active retention policy

Resolution and Override Workflow Tracking

Given a reviewer or admin resolves a detection (true positive, false positive) or overrides masking to unmask When they submit the action Then the system requires a 10–500 character justification for overrides and false-positive markings And captures before_state and after_state of mask status, justification, actor_id, timestamp, and links to the original detection via correlation_id And the UI displays a chronological action history per detection And an audit record is created for any reversal or re-resolution

Secure Access and Exports (RBAC + Default Masking)

Given role-based permissions exist (Audit.View, Audit.Export, Export.Unmasked, Reports.View) When a user attempts to view audit logs, dashboards, or export data Then access is allowed only if the user possesses the required permission and denied with HTTP 403 otherwise, with the decision logged as an audit event And any export generated is masked by default, replacing PII/unmasked originals with category tokens (e.g., [PII-<category>-<hash>]) And only users with Export.Unmasked can request unmasked exports; others cannot see or request the option And each export operation logs requestor, filter scope, masked/unmasked flag, file format, and download timestamp

Dashboards: Volumes, Resolution Times, Trends by Program

Given a user with Reports.View opens the ReID Guard dashboards When they select filters (time range, program, detection category, reviewer) Then the dashboard shows: counts by detection_category, open vs resolved counts, median and 90th percentile resolution time, and weekly trend charts per program And all widgets refresh with the selected filters and reflect data with freshness of 15 minutes or less And each widget supports CSV export that honors masking rules and current filters

False-Positive Rate Reporting

Given reviewers mark detections as true positive or false positive during resolution When a report is generated for a selected period and scope Then the system computes false-positive rate per detection_category and program as FP / (FP + TP), with counts displayed And categories with fewer than 30 total labeled events are marked as "insufficient data" rather than showing a rate And FP rates are displayed to two decimal places in dashboards and included in CSV exports

Configurable Retention Policies and Automated Purge

Given an admin configures retention periods for audit logs and unmasked originals (e.g., logs=365 days, unmasked=30 days) When the nightly purge job runs Then records older than their respective retention periods are permanently deleted from primary and replica storage And a purge summary audit event records counts purged by data type, time window, and job_id And legal holds can be applied per program to suspend purge; held records are not deleted and the hold metadata (reason, actor, start date) is visible in settings and audit logs And requests for purged items return 404/Not Found with no residual PII

Publish Outcome Snapshot and Traceability

Given feedback or decisions are published to applicants or sponsors When the publish action is executed Then the system stores a tamper-evident snapshot containing the visible content, mask states, and rule_version, along with a SHA-256 hash And the snapshot is linked to the publish audit event and the underlying detections/resolutions via correlation_id And an authorized user can retrieve the snapshot and verify its hash to confirm non-alteration

Contextual Reviewer Identity Shielding

"As a review chair, I want the system to flag wording that could reveal reviewer identity so that blind review remains intact."

Description

Specialized detection for content that could disclose reviewer identity or relationships (e.g., “as your advisor,” mention of specific labs, courses, or small-cohort identifiers). Uses heuristic context windows and curated phrase libraries to flag and optionally generalize wording through templates (e.g., replace with “a committee member”). Offers inline guidance in the reviewer editor to prevent identity-revealing language proactively, with program-configurable strictness and exception handling for sanctioned disclosures.

Acceptance Criteria

Inline Identity Phrase Detection in Reviewer Editor

Given a reviewer types or pastes text into the MeritFlow reviewer editor When the text includes identity-revealing phrases from the curated library or rule patterns Then the system highlights the risky span within 250ms at P95 and shows an inline tooltip with a neutral alternative suggestion And no highlight is shown for control phrases that are not in the library or patterns (false positives ≤ 5% on the internal evaluation set) And when the reviewer accepts the suggested replacement, the warning clears immediately and the edited text is retained And when the reviewer dismisses the warning, an audit event is recorded (user id, timestamp, phrase category, text hash) and the dismissal persists until the text changes

Pre-Publish Auto-Generalization and Masking

Given a reviewer initiates Share/Publish for feedback or decisions When the pre-publish scan runs on comments, admin notes, and attachments Then any detected identity-revealing phrases are either auto-generalized using the configured template set or masked, according to program policy And the reviewer is shown a diff preview of all changes before finalizing unless policy requires auto-apply with no override And publish is blocked until all issues are resolved or policy-sanctioned exceptions exist And the applicant-facing view contains only generalized/masked text; the original text is retained in an audit trail accessible only to authorized staff And detection recall on the identity benchmark ≥ 95% and precision ≥ 90% in CI quality gates

Program-Level Strictness Configuration

Given a program admin sets strictness to Lenient, Standard, or Strict in ReID Guard settings When the setting is saved Then the active rule/phrase set updates immediately for both inline editor and pre-publish scan And Lenient flags only explicit self-relationship phrases (e.g., "my advisee", "as your advisor"); Standard additionally flags lab/course and affiliation cues; Strict adds indirect hints (e.g., small cohort sizes, specific equipment, grant numbers) And switching levels is audit-logged and reflected in the next scan without requiring user logout And unit/regression tests verify level-specific detection with ≥ 95% pass rate on the curated test suites per level

Sanctioned Disclosure Exception Workflow

Given a program permits certain disclosures (e.g., panelist identification to sponsors) When an authorized admin creates an exception scoped by program/round/application with an expiry date and justification (≥ 15 characters) Then content matching the exception is allowed to publish without blocking and displays a "Sanctioned Disclosure" badge to staff And after expiry or scope mismatch, the same content is flagged and blocks publish per policy And all exception create/update/delete actions are audit-logged and permission-gated; unauthorized users cannot create exceptions And reporting surfaces counts of sanctioned disclosures by program and period

Contextual Detection Across Sentences and Attachments

Given a reviewer writes content where identity is inferable only by combining nearby sentences or metadata When related clues occur within a 2-sentence or 300-character window, or across comment text and attachment filename/content Then the system flags the composite risk with a single actionable warning referencing all contributing spans And attachments in PDF/DOCX/TXT are text-extracted and images are OCR-processed up to 10 MB total; P95 scan time ≤ 2 seconds for 10 MB And if text extraction fails, the user is notified with a retry option and publish is blocked until the attachment is removed/replaced or an exception is granted And composite-rule precision on the test corpus ≥ 88% with recall ≥ 92%

Small Cohort Identifier and Relationship Cue Detection

Given content includes small-cohort identifiers (e.g., "<=20 students", specific course section codes), niche lab names, or relationship cues ("my student", "our dissertation meeting") When strictness is Standard or Strict Then these cues are flagged; the reviewer can apply one-click generalization to "a course I taught", "a committee member", or "a lab in the field" per template And after generalization, the character count delta is within ±30% of the original sentence and no tokens remain from the original specific identifiers And Undo restores the original text in one step and re-triggers the warning And the phrase library is admin-editable; updates propagate within 10 minutes and are versioned

Milestone Release Planner

Schedule award disbursements by milestones and deliverables with auto-gates, evidence checklists, and date-based triggers. Sends smart reminders to applicants, routes evidence for quick review, and auto-creates ERP-ready vouchers upon approval—eliminating spreadsheets and preventing premature payouts.

Requirements

Milestone Template Builder

"As a program manager, I want to configure standardized milestone templates with deliverables and evidence checklists so that disbursement schedules are consistent and easy to launch across awards without rebuilding plans from scratch."

Description

Enable program managers to design reusable milestone plans per award that define deliverables, evidence checklists, acceptance criteria, and due dates relative to program start/award dates. Support configurable checklist items (file types, forms, links), conditional requirements per applicant segment, dependency ordering, and time offsets (e.g., +30 days after contract). Provide versioning, cloning across programs, and real-time timeline preview. Integrate with MeritFlow’s brief-to-rubric builder to pull objectives and align deliverables, and write template metadata to the program schema for reporting and automation.

Acceptance Criteria

Relative Due Dates with Anchors and Real-Time Preview

Given I add two deliverables with offsets of +30 days from Contract Signed and +7 days from Award Date, When I set sample anchor dates (Program Start: 2025-09-01, Award Date: 2025-09-10, Contract Signed: 2025-09-20), Then the timeline preview displays computed due dates of 2025-10-20 and 2025-09-17 respectively. Given a deliverable is anchored to Program Start with an offset of 0 days, When I change the sample Program Start from 2025-09-01 to 2025-09-15, Then the previewed due date updates accordingly within 1 second. Given a deliverable is anchored to Contract Signed and that anchor is unset in the sample, When viewing the preview, Then the due date displays as "TBD" with the relative rule "Contract Signed +30 days" and no calendar date. Given I mix different anchors across deliverables, When I save the template, Then all anchor rules and offsets persist and are retrievable for reporting and automation.

Configurable Evidence Checklist Validation

Given I add a checklist item of type File Upload with allowed types PDF, DOCX and a maximum of 2 files, When an applicant attempts to upload a JPG in a sandbox submission, Then the upload is blocked with the message "Only PDF, DOCX up to 2 files allowed." Given I add a checklist item of type Form and select "Progress Report v1", When the template is published, Then the deliverable requires completion of "Progress Report v1" before submission. Given I add a checklist item of type External Link constrained to the pattern https://example.com/*, When an applicant enters https://malicious.com, Then the link is rejected with a validation error. Given I mark a checklist item as Optional, When the applicant submits the deliverable without that item, Then the system allows submission without errors.

Conditional Requirements by Applicant Segment

Given I define a segment condition "Applicant Type = Faculty" and attach Deliverable A as Required only for this segment, When previewing the template as Applicant Type = Faculty, Then Deliverable A is visible and required. Given the same condition, When previewing as Applicant Type = Student, Then Deliverable A is hidden or marked Not Required. Given I define a composite condition "Budget > 50000 AND International = true" for Deliverable B, When an applicant record meets both conditions, Then Deliverable B is included; When either condition is not met, Then Deliverable B is excluded. Given an invalid condition expression, When saving the template, Then the save is blocked with a clear error explaining the invalid rule.

Dependency Ordering and Gating

Given Deliverable B depends on Deliverable A, When I set B's due date earlier than A's, Then the system blocks the change with "Due date must be after dependency." Given a circular dependency A -> B and B -> A, When I attempt to save, Then the system prevents save and identifies the cycle. Given Deliverable B depends on A, When an applicant tries to submit B before A is accepted, Then the submission is disabled with a message referencing the dependency. Given multiple dependencies A and C for B, When A and C are accepted, Then B becomes submittable automatically.

Template Versioning: Draft, Publish, and Assignment

Given I create template version 2.0 from version 1.0, When I publish 2.0, Then version 1.0 remains immutable and assigned programs continue using 1.0 until explicitly migrated. Given a published version, When I attempt to edit a deliverable's offset, Then the system denies edits with the message "Published versions are read-only. Create a new version." Given I assign version 2.0 to Program X, When Program X opens the milestone plan, Then it reflects version 2.0 rules; When I roll back to 1.0, Then it reverts accordingly. Given a draft version, When I run validation, Then unresolved references (e.g., missing forms, segments) are flagged and publishing is blocked until resolved.

Clone Template Across Programs with Mapping

Given I select Template T from Program A, When I clone to Program B, Then all deliverables, offsets, dependencies, checklist items, and conditions are copied. Given Program B lacks the form "Progress Report v1" used by Template T, When cloning, Then I am prompted to map to an equivalent form or skip; publishing is blocked if required items remain unmapped. Given I lack the Program Manager role in Program B, When I attempt to clone into Program B, Then the operation is denied with an authorization error. Given the clone completes, When I compare the clone to the source, Then IDs are regenerated but human-readable names and structure remain identical.

Integrate with Brief-to-Rubric and Write Metadata to Program Schema

Given Program A has objectives defined in Brief-to-Rubric, When I open the Template Builder, Then I can search and attach objectives to deliverables and see objective IDs and titles on each deliverable. Given deliverables are aligned to objectives, When I save the template, Then the template metadata persisted to the program schema includes deliverables, offsets, anchors, dependencies, checklist configurations, segment conditions, and objective IDs in a queryable structure. Given the template is published, When I query the reporting layer for Program A, Then I can retrieve the metadata fields for automation (e.g., triggers based on due dates and dependencies) without reading unstructured text. Given I detach an objective from a deliverable and save a new version, When I query the schema, Then previous version metadata remains intact and the new version reflects the change.

Conditional Auto-Gates Engine

"As a finance approver, I want automatic gates that prevent voucher creation until required approvals and checks are satisfied so that funds cannot be released prematurely or outside policy."

Description

Introduce a no-code rules engine that blocks disbursements until defined conditions are met, including evidence item approvals, checklist completion, compliance attestations, and conflict-of-interest clearance. Allow AND/OR logic, per-milestone thresholds, partial release rules, and preflight validation to surface unmet gate conditions. Provide rule simulation, inline explanations of blocks, and audit of gate evaluations. Integrate with eligibility data, review outcomes, and finance flags to prevent premature payouts and enforce policy consistently.

Acceptance Criteria

AND/OR Gate Evaluation for Milestone Disbursement

Given a milestone M with rule R = (approved_evidence_count >= 3 AND compliance_attested = true) AND conflict_clear = true When approved_evidence_count = 3 AND compliance_attested = true AND conflict_clear = true Then gate_state = PASS and M.disbursement_eligibility = ELIGIBLE Given the same R When approved_evidence_count = 2 OR compliance_attested = false OR conflict_clear = false Then gate_state = BLOCK and M.disbursement_eligibility = BLOCKED and no voucher is created Given a milestone M with rule R2 = (peer_review_score >= 85 OR director_override = true) When peer_review_score = 84 AND director_override = true Then gate_state = PASS Given the same R2 When peer_review_score = 84 AND director_override = false Then gate_state = BLOCK

Per‑Milestone Threshold and Partial Release Rules

Given milestone M budget = 10000 and partial rule: 50% release when approved_evidence_ratio >= 0.6; 100% release when approved_evidence_ratio = 1.0 When approved_evidence_ratio = 0.6 and no compliance hold Then voucher_amount = 5000.00 and remaining_balance = 5000.00 and gate_state = PARTIAL_PASS Given the same rule When approved_evidence_ratio = 1.0 and no compliance hold Then cumulative_voucher_amount = 10000.00 and remaining_balance = 0.00 and gate_state = PASS Given the same rule When approved_evidence_ratio = 0.4 Then voucher_amount = 0.00 and gate_state = BLOCK Given prior partial release of 5000.00 When approved_evidence_ratio transitions from 0.6 to 1.0 Then new_voucher_amount = 5000.00 and cumulative_voucher_amount <= 10000.00

Preflight Validation Surfaces Unmet Gate Conditions

Given a user schedules disbursement for milestone M with unmet gates When preflight validation is run Then the system returns HTTP 409 with code GATE_UNMET and a list of failed_conditions each including gate_id, field, expected, actual, and remediation_hint, and no voucher or state change occurs Given M meets all gates When preflight validation is run Then the system returns HTTP 200 with preflight_status = CLEAR in under 2 seconds (p95) and indicates would_release_amount

Rule Simulation Shows Outcomes Without Side Effects

Given a program manager runs rule simulation for milestone M at snapshot_date = today When simulate is executed Then the system returns, for each gate, evaluation_result (PASS/BLOCK/PARTIAL), evaluated_inputs, rule_version, and would_release_amount and records an audit entry with type = SIMULATION and no voucher, emails, or reminders are produced Given simulate is run with hypothetical input overrides (e.g., compliance_attested = true) When simulate is executed Then results reflect overrides and are clearly labeled as what_if = true

Inline Block Explanations on Payout Attempt

Given an applicant or manager attempts to trigger payout and gates fail When the UI renders the payout panel Then an inline explanation is displayed summarizing failed gates with human-readable messages referencing the exact unmet conditions and deep links to the related evidence/checklist items and last_evaluated_at timestamp, and the same data is available via GET /milestones/{id}/gate-status Given gates subsequently pass When the page is refreshed or reevaluation completes Then the block explanation is removed and the payout action becomes enabled

Audit Log of Gate Evaluations

Given any gate evaluation occurs (preflight, simulation, scheduled run) When the evaluation completes Then an immutable audit record is written containing timestamp, actor/system, milestone_id, applicant_id, rule_id, rule_version, inputs_hash, outcome, and release_amount, and it is retrievable by admins via audit API and exportable as CSV Given an audit record exists When a user attempts to modify it Then the system prevents the change and records an additional audit entry for the attempt

Integration with Eligibility, Reviews, and Finance Flags

Given gates reference fields from eligibility, reviews, and finance modules (eligibility_status, review_decision, finance_hold) When eligibility_status = verified AND review_decision = approve AND finance_hold = false Then gate_state = PASS Given any upstream value changes to a referenced field When finance_hold toggles true OR eligibility_status becomes pending OR review_decision = reject Then gate_state transitions to BLOCK within 30 seconds and pending payouts are prevented and any scheduled vouchers for this milestone are paused

Evidence Submission & Reviewer Routing

"As an applicant, I want a clear place to upload required evidence and receive timely reviews so that I know exactly what is needed and can get releases without back-and-forth emails."

Description

Offer a guided applicant workspace to submit milestone evidence with per-item instructions, format validation, and metadata capture. Automatically route submissions to the appropriate reviewers based on program rules, expertise tags, workload, and conflict rules. Support parallel or sequential reviews, SLA timers, inline annotations, request-changes cycles, and clear approve/reject outcomes. Provide visibility of status to applicants and reviewers, with accessible UI and mobile-friendly upload.

Acceptance Criteria

Guided Evidence Submission With Format & Metadata Validation

Given an applicant opens a milestone workspace with an evidence checklist When they add each evidence item via file upload or URL Then the UI displays per-item instructions and required fields And only allowed file types per item are accepted per program configuration And files exceeding the configured max size are blocked with an inline error showing the limit And required metadata fields enforce type and pattern validation (dates, numbers, enums) And the applicant can save a draft without completing all required items And attempting to submit requires all required items and metadata to be complete And the successful submission time, item counts, and metadata are stored in the audit log

Automatic Reviewer Routing by Rules, Expertise, Workload, and Conflicts

Given a submission transitions to Ready for Review When the routing engine runs Then the system selects at least the configured minimum number of reviewers And each selected reviewer matches required role and has expertise tag overlap at or above the configured threshold (or includes all required tags) And no selected reviewer has a conflict per program conflict rules (self, same organization, declared relationship, prior co-author) And no selected reviewer exceeds the configured maximum concurrent assignments And if eligible reviewers are fewer than required, the system notifies the coordinator within 5 minutes and places the item in an Unassigned queue And the assignment decision records reviewer IDs, rule checks, and timestamp in the audit log

Parallel vs Sequential Review Flow Execution

Given the program review mode is configured as Parallel or Sequential for the milestone When reviewers are assigned Then for Parallel mode, all invitations are sent within 2 minutes and the decision engine computes outcome once the configured quorum is reached And for Sequential mode, the next reviewer is invited only after the prior review is submitted or the SLA expires And the system prevents a final decision until the configured quorum or sequence completion is met And the current stage and remaining steps are visible on the submission timeline to applicants and reviewers per blind settings

Review SLA Timers, Reminders, and Escalations

Given a review due time is configured for the program (e.g., 72 hours) When an assignment is created Then the SLA countdown starts and is displayed to the assigned reviewer And reminder notifications are sent at the configured intervals before due (e.g., 48h, 24h) And if the SLA is breached, the assignment is escalated to the configured backup within 15 minutes and the coordinator is notified And the SLA clock pauses while the submission is in a Request Changes state and resumes upon applicant resubmission And all reminders and escalations are recorded in the audit log

Inline Annotations and Request Changes Cycle

Given a reviewer is viewing an evidence item When they add inline annotations and submit a Request Changes decision Then annotations are saved with precise coordinates or excerpt references and reviewer identity/time And the applicant receives a consolidated change request listing items to update and annotation count per item And the applicant can upload new versions per item while preserving prior versions and version history And upon resubmission, the original reviewer is notified and can compare versions side-by-side And the system prevents approval until all requested changes are addressed or withdrawn

Approve/Reject Outcomes and Voucher Creation Gate

Given all required reviews are complete When the outcome is Approve Then the milestone status updates to Approved And an ERP-ready voucher payload is generated with the configured template and required fields (amount, payee, GL code, milestone ID) and queued or sent to the ERP integration endpoint And the voucher is not generated if financial compliance gates are not met And the applicant is notified of approval with amount and next steps And the audit log captures the outcome, approver(s), and voucher ID When the outcome is Reject Then the milestone status updates to Rejected And the applicant is notified with standardized reasons And no voucher is generated

Role-Based Status Visibility, Accessibility, and Mobile Upload

Given blind review mode and role permissions are configured When an applicant or reviewer views the submission Then applicants can see item-level status, requested changes, and gating dates but not reviewer identities in blind mode And reviewers can see only their assignments, SLA timers, and anonymized applicant data per program rules And the UI meets WCAG 2.1 AA: keyboard navigation, logical focus order, ARIA labels, color contrast ≥ 4.5:1, and screen-reader readable labels and errors And on mobile (iOS and Android), applicants can upload via camera, photo library, or files, with progress indicators and resumable uploads up to the configured size limit over variable network conditions

Smart Reminders & Date-Based Triggers

"As a grant coordinator, I want automated reminders and triggers tied to milestone dates so that applicants and reviewers stay on track without manual chasing."

Description

Implement a scheduling and notification system that sends pre-due, due, and overdue reminders for milestones and evidence items, and triggers next-step actions on approval (e.g., open next milestone window). Support timezone-aware delivery, quiet hours, escalation paths, calendar invites, and digest modes. Allow program-level templates with dynamic placeholders and conditional audiences for applicants, reviewers, and finance stakeholders.

Acceptance Criteria

Pre-Due, Due, and Overdue Milestone Reminders

Given a milestone with a due date and reminder offsets configured for -7d, -1d, 0d, and +3d When the scheduled send time occurs in the recipient’s timezone Then the system sends exactly one reminder per offset using the selected template and records a delivery log entry with timestamp and recipient ID And reminders are delivered within 5 minutes of the scheduled time And no reminder is sent if the milestone or all required evidence is marked Complete before the scheduled send time And transient delivery failures are retried up to 3 times with exponential backoff; final failures are logged and surfaced in the notifications dashboard

Timezone-Aware Delivery and Quiet Hours Enforcement

Given a recipient with a stored timezone and a program with configured quiet hours When a reminder’s scheduled time falls within the recipient’s quiet hours Then the send is deferred to the next available minute outside quiet hours in the recipient’s timezone and logged as deferred And if the recipient has no valid timezone, the program default timezone is used; if none, UTC is used And DST transitions are respected such that no duplicate or skipped reminders occur around the transition window And the delivery timestamp visible to the recipient is displayed in their local timezone

Escalation for Overdue Evidence and Milestones

Given an overdue milestone or evidence item and an escalation policy of Tier 1 at +3d and Tier 2 at +7d When the item remains incomplete at each escalation threshold Then an escalation notification is sent to the configured audience (e.g., assigned reviewer for Tier 1, finance stakeholder for Tier 2) and logged And escalations cease immediately once the item is completed or the due date is extended And duplicate escalations to the same recipient for the same item and tier are prevented And the escalation notification includes the item, days overdue, link to review, and current assignee

Calendar Invites for Milestone Due Dates

Given calendar invites are enabled for milestone due dates When a reminder is generated for a due date Then the notification includes a valid .ics file with a stable UID, start time set to the due date/time in the recipient’s timezone, and a link back to the MeritFlow portal And when the due date/time changes, an updated .ics (METHOD:REQUEST) is sent with the same UID; if the milestone is canceled/closed early, a cancel .ics (METHOD:CANCEL) is sent And exactly one active invite exists per recipient per milestone; duplicates are not created

Digest Mode for Reminders

Given a recipient has enabled daily or weekly digest mode and has pending reminders in that period When the digest send time (e.g., 08:00 local) occurs Then a single digest email is sent summarizing upcoming (next 7 days), due today, and overdue items with counts and grouped by program And individual reminders covered by the digest window are suppressed for that recipient And recipients can opt out of digest via a link that updates preferences immediately and is honored on the next cycle

Program Templates with Dynamic Placeholders and Conditional Audiences

Given a program-level template with placeholders (e.g., {applicant_name}, {milestone_name}, {due_date_local}, {evidence_list}, {portal_link}) and audience rules (Applicants with incomplete evidence; Assigned Reviewers; Finance when approved) When the system renders and sends a reminder Then all placeholders resolve without unresolved tokens; missing data uses a defined fallback or hides the line And audience conditions select only recipients who meet the rule at send time; recipients are deduplicated across roles And a preview shows the fully rendered message for a selected test record before enabling the template

Approval Triggers to Open Next Milestone and Create ERP-Ready Voucher

Given a milestone configured with next-step actions and ERP voucher generation When all required evidence is approved and the milestone status transitions to Approved Then the next milestone window opens automatically with the correct start/end dates and visibility rules And an ERP-ready voucher is created exactly once with required fields (program ID, payee, amount, milestone ID) and queued to the finance integration And if voucher creation fails, the system retries per policy and surfaces a "Voucher Pending" alert without reopening or duplicating actions; all events are audit-logged

ERP Voucher Generation & Export

"As a finance manager, I want approved milestones to generate ERP-ready vouchers with correct accounting codes so that disbursements post accurately without manual spreadsheet work."

Description

Automatically create ERP-ready voucher records upon milestone approval with mapped chart-of-accounts, fund, project, and cost center codes. Support vendor/payee mapping, split allocations, currency handling, tax/withholding fields, and unique voucher IDs. Provide export via secure CSV/SFTP and REST API connectors with idempotency, error handling, retries, and status callbacks. Include finance review/approval, batch exports, and reconciliation dashboards to confirm successful posting.

Acceptance Criteria

Auto Voucher Creation on Milestone Approval

- Given a milestone is approved by a user with Finance Reviewer role and all required finance fields are complete, When the approval event is processed, Then a voucher is created within 5 seconds with a unique voucher_id and status "Draft" in MeritFlow. - And the voucher contains mapped chart_of_accounts fields (account, fund, project, cost_center), vendor_id, gross_amount, currency, tax_withholding fields, and any defined split lines. - And an immutable audit log entry is written with milestone_id, approver_id, timestamp (UTC), and voucher_id. - And idempotency is enforced: reprocessing the same approval event does not create a duplicate; the same voucher_id is returned.

Vendor/Payee Mapping Validation

- Given a voucher is being generated, When vendor/payee mapping is resolved, Then the selected ERP vendor_id matches the configured mapping for the applicant or award. - If mapping is missing or invalid, Then voucher status is set to "Needs Vendor Setup", export is blocked, and a notification is sent to Finance with a remediation link. - Vendor legal name, tax_id, and remittance address are validated against format rules; any failures are surfaced as field-level errors and logged. - If an alternate payee is flagged, Then the payee override is applied and recorded in the audit log.

Split Allocations and COA Distribution

- Given a milestone has split allocations across funds/projects/cost centers, When the voucher is created, Then a line item is generated per split with correct amount or percentage. - The sum of line items equals the gross_amount within a 0.01 currency tolerance; otherwise creation fails with a reconciliation error. - Each line item’s chart_of_accounts combination is validated against the COA mapping table; invalid combinations are rejected with a specific error code. - Up to 500 line items are supported per voucher with creation completing in under 7 seconds for the maximum case.

Multi-Currency and Tax/Withholding Handling

- Given award currency may differ from base currency, When creating the voucher, Then the conversion uses the configured rate source for the milestone approval date and records both transaction_amount (award currency) and base_amount (base currency). - Rounding follows configured rules (banker’s rounding) to 2 decimal places; discrepancies greater than 0.01 are flagged. - Applicable withholding/tax rates are applied based on vendor/tax profile; fields tax_rate, tax_amount, net_payable are populated; if tax_exempt is true, Then tax_amount is 0. - The voucher is blocked from export if the rate source is unavailable; a retry is scheduled and the failure is logged.

CSV/SFTP Batch Export with Idempotency and Retries

- Given vouchers are in "Approved for Export" status, When a scheduled or manual batch export runs, Then a CSV is generated matching the configured ERP schema and file name pattern {env}_{yyyymmddHHMM}_{batchId}.csv. - The file is transmitted via SFTP using key-based authentication; on success, vouchers are marked "Exported" with file_reference and batchId stored. - Idempotency is enforced: re-running the same batchId does not duplicate vouchers in the file or in the ERP. - Network or SFTP errors trigger up to 5 retries with exponential backoff (max 5 minutes); partial failures are detected, logged per voucher, and only failed vouchers are retried. - A checksum (SHA-256) of the file is computed and stored; the ERP receipt acknowledgment is captured when available.

REST API Export Connector with Robust Error Handling

- Given ERP REST endpoint and credentials are configured, When exporting a voucher, Then POST the payload per schema with Idempotency-Key set to voucher_id and include correlation_id for tracing. - On HTTP 2xx, mark the voucher as "Exported" and store the ERP reference_id; on HTTP 409 duplicate, treat as success and reconcile by reference_id. - On HTTP 4xx/5xx or network timeouts, apply retry policy (max 6 attempts, exponential backoff to 10 minutes) and capture full error details. - Status callbacks/webhooks from ERP are authenticated and update voucher status to "Posted" on success or "Failed" with reason on error; all transitions are audit-logged.

Finance Review Gate and Reconciliation Dashboard

- Given vouchers are created, When Finance performs review, Then only users with Finance Approver role can move a voucher to "Approved for Export"; changes require re-approval. - The reconciliation dashboard displays counts by status (Draft, Needs Vendor Setup, Approved for Export, Exported, Posted, Failed), filterable by program, fund, project, and date range. - Each voucher row shows last export attempt time, attempt count, channel (CSV/SFTP or REST), reference_ids, and any error messages. - A "Reconcile" action matches Exported vouchers to ERP Posted records via reference_id or amount/date matching; successful matches update status to "Posted" and record reconciled_by and timestamp. - Dashboard loads within 2 seconds for up to 5,000 vouchers and supports CSV download of the current view.

Funding Cap & Duplicate Disbursement Guard

"As a program director, I want automatic guards against overpayment and duplicates so that total disbursed funds never exceed the award budget or policy constraints."

Description

Enforce award- and fund-level caps by calculating cumulative disbursements across milestones and blocking actions that would exceed limits. Detect and prevent duplicate or overlapping payouts by checking payee, amount, milestone, and time windows, with configurable tolerances. Provide remaining-balance visibility, override controls with justification and audit logging, and alerts when projected releases approach caps.

Acceptance Criteria

Award Cap Enforcement at Disbursement Approval

Given an award with a total cap of $100,000 and cumulative approved-or-paid disbursements of $95,000 And a milestone request for $6,000 is pending approval When a reviewer attempts to approve the disbursement Then the system blocks approval and displays an error: "Exceeds award cap by $1,000" And the disbursement remains in Pending status with no voucher created And an audit event is recorded capturing user, timestamp, requested amount, cap, overage amount, and context And if another approver attempts the same action concurrently, only one approval attempt may succeed such that the cap is never exceeded

Fund-Level Cap Enforcement Across Awards

Given a fund with a cap of $500,000 And the aggregate of paid and approved-but-unpaid disbursements across linked awards equals $498,500 When an approver attempts to approve a disbursement of $2,000 from any linked award Then the system blocks the approval and shows: "Exceeds fund cap by $500" And the disbursement remains in Pending status with no voucher created And an audit event is recorded including fund ID, award ID, amounts, user, and timestamp And aggregation includes multi-currency amounts normalized to the fund currency using the system rate on approval time

Duplicate Disbursement Detection Within Tolerance

Given duplicate detection tolerance is configured as amount ±$25 or ±1% (whichever is greater) and a time window of 30 days And there exists a prior paid or approved disbursement to Payee X for Milestone M of $2,000 dated within the last 20 days When a reviewer attempts to approve a new disbursement to Payee X for $2,010 for the same milestone Then the system blocks approval and flags "Potential duplicate within tolerance" And requires either cancellation or an authorized override before proceeding And the duplicate check also triggers if milestones differ but service periods overlap within the configured time window

Remaining Balance Visibility on Milestone Request

Given a user opens a milestone disbursement request form When the page loads Then the UI displays the award remaining balance and fund remaining balance in currency with two decimals And when the requested amount field is edited, both remaining balances recalculate immediately to reflect the proposed approval And tooltips or inline help disclose how balances are calculated (paid + approved-but-unpaid) And values are sourced from the latest committed data to avoid stale totals

Override with Justification and Audit Trail

Given an approval is blocked due to cap exceedance or potential duplicate And the acting user holds the "Finance Manager" override permission When the user selects Override Then the system requires a justification text (minimum 20 characters) and a reason code from a configurable list before enabling Confirm And upon confirmation, the approval proceeds and a non-editable audit record is created capturing user, role, timestamp, IP, original validation errors, justification text, reason code, and before/after amounts And the audit record is visible in the award’s Compliance Log and exportable

Cap Threshold Alerts on Projected Releases

Given a cap threshold alert is configured at 80% of the award and fund caps And a set of scheduled or pending approvals would bring utilization to ≥80% within the next 30 days When the threshold is crossed by any approval or schedule update Then the system sends an in-app alert and email to designated program and finance contacts within 5 minutes And the alert includes award/fund IDs, current utilized amount, remaining balance, and the drivers (milestones) of the projection And alerts suppress duplicates for the same threshold crossing within a 24-hour period

ERP Voucher Creation Guarded by Checks

Given a disbursement has been approved When cap enforcement and duplicate detection validations are executed Then a voucher is created for the ERP only if all validations pass or a qualified override was completed And if validations fail, no voucher is created and a failure event with reasons is logged and surfaced to the approver And the ERP payload contains a validationPassed flag and reference IDs to any override audit records when applicable

Audit Trail & Compliance Reporting

"As a compliance officer, I want end-to-end audit trails and reports for each release so that I can verify policy adherence and respond quickly to audits."

Description

Capture an immutable, time-stamped audit trail of all milestone events: evidence submissions, reviews, approvals, gate evaluations, reminders sent, voucher generation, and exports. Provide filters and exports for auditors by program, award, milestone, user, and timeframe, with chain-of-custody for evidence files and version history of rules and templates. Support retention policies and access-controlled sharing for compliance reviews.

Acceptance Criteria

Immutable Audit Log for Milestone Lifecycle Events

Given a user or system process triggers a milestone event (evidence submitted, review recorded, approval/denial, gate evaluation, reminder sent, voucher generated, or data export) When the event is committed Then an audit entry is written once with fields: event_type, program_id, award_id, milestone_id, actor_id_or_service, actor_role, timestamp_utc_ms, request_id, source_ip, user_agent, outcome_status, and metadata And the audit entry is assigned an append-only sequence_id and linked via hash_chain_previous and hash_chain_current (SHA-256) And attempts to update or delete the entry via UI or API return 403 and are themselves logged And retrieving the audit entry by request_id returns exactly one record And timestamps are in UTC with millisecond precision and monotonic within a request

Chain-of-Custody for Evidence Files

Given an applicant or staff uploads evidence files to a milestone When the upload completes Then the system records a custody entry with file_id, storage_uri, sha256_checksum, uploader_id, timestamp_utc_ms, source_ip, and size_bytes And any subsequent view, download, virus-scan, or transfer writes an immutable audit entry referencing file_id And uploading a replacement creates a new version with incremented version_number and prior_version_id And checksum verification after download matches the stored checksum And the system can produce a chronological custody report for a file within 2 seconds for up to 500 custody events

Rules and Templates Version History & As-Of Reconstruction

Given program staff modify milestone gates, evidence checklists, scoring rubrics, or reminder templates When the change is saved Then a version record is created with version_id, changed_by, timestamp_utc_ms, change_summary, and a diff of modified fields And milestone evaluations store the rule_version_id used at decision time And auditors can re-run an evaluation as-of a past timestamp and reproduce the same decision outcome And reverting to a prior version creates a new version record and does not delete history

Auditor Filters and Search Performance

Given an auditor applies filters by program, award, milestone, user, and timeframe When the query is executed Then results include only matching audit entries with the defined audit schema columns And the first page (100 records) returns in <= 3 seconds on datasets up to 1,000,000 entries And results are paginated, sortable by timestamp and event_type, and respect a selected display timezone without altering stored UTC timestamps And users lacking access to a program receive zero results with HTTP 200 And response metadata echoes applied filters and pagination info

Export Integrity and Data Lineage

Given an auditor requests an export with specific filters and fields When the export job completes Then the system produces CSV and JSON files plus a manifest.json containing record_count, time_range, filter_summary, schema_version, and SHA-256 hashes per file And the export bundle includes a signature.txt with an HMAC-SHA256 signature verifiable by the tenant key And the bundle can be submitted to a validation endpoint that verifies hashes and signature and returns Pass And exports over 50,000 records stream and complete within 60 minutes or return a retryable job_id within 10 seconds And every export download is logged with requester_id, timestamp_utc_ms, and source_ip

Access-Controlled Audit Sharing for Compliance Reviews

Given a program owner creates an auditor access package When they define scope (programs, awards, timeframe, event types), redaction rules, and expiry Then the system generates a read-only access link bound to scope, requires 2FA on first access, and can enforce an optional IP allowlist And all views, searches, and downloads within the package are logged and visible to the owner And the owner can revoke access and tokens become invalid within 60 seconds And records outside scope are not accessible; attempts return 403 and are audited

Retention Policies and Legal Holds

Given retention policies are configured per artifact type (audit logs, evidence files, exports) per program When data reaches retention end and is not under legal hold Then a purge job executes within 24 hours, deletes content, retains a tombstone with minimal metadata and purge_reason, and generates a purge report for admins And any access to purged content returns 404 and is logged And legal holds prevent purge until removed; all hold additions and removals are audited And retention policy changes are versioned and do not retroactively shorten existing retention windows

ERP Sync Guard

Pre-flight checks and bi-directional sync with your ERP to create vendors, bills, and payment batches safely. Maps GL accounts and cost centers, catches posting errors early, and reconciles statuses back to MeritFlow so finance and program teams stay perfectly aligned without manual re-entry.

Requirements

Secure ERP Connection & Credential Vault

"As a system administrator, I want to securely connect MeritFlow to our ERP with least-privilege credentials so that data can sync reliably without exposing sensitive finance data."

Description

Provide a secure, centralized configuration experience to connect MeritFlow to supported ERPs (e.g., NetSuite, Oracle, SAP, Workday, Microsoft Dynamics). Support OAuth2, token/API key, basic auth, and SFTP credentials with at-rest and in-transit encryption, key rotation, and least-privilege scopes. Include sandbox/production environment toggles, IP allowlisting, endpoint whitelisting, connection health checks, and a "Test Connection" workflow. Enforce role-based access control for who can view/update secrets, and maintain a full audit of credential changes. Allow multiple ERP tenants per organization and per-program routing. Expose a connection status API for other modules to gate sync operations.

Acceptance Criteria

Supported Authentication Methods Configuration

Given I am an Organization Integration Admin on MeritFlow When I create a new ERP connection and choose an ERP type (NetSuite, Oracle, SAP, Workday, Microsoft Dynamics) Then I can select an authentication method from OAuth2, API token/key, Basic Auth, or SFTP And the form displays only the required fields for the selected ERP and method (e.g., OAuth2: client ID/secret, auth URL, token URL, scopes; API key: key field; Basic: username/password; SFTP: host, port, username, key/password) And scope/permission fields are required and constrained to least-privilege selections for that ERP When I submit valid values Then the connection record is created and secrets are stored without displaying plaintext in the confirmation And secret inputs are masked in the UI and not retrievable via any GET API after save When required fields are missing or invalid Then the form blocks save and displays field-level validation errors

Credential Encryption and Automated Key Rotation

Given a connection with credentials has been saved When credentials are transmitted from browser to server Then the connection must use transport encryption and reject non-TLS requests When credentials are stored server-side Then secrets are persisted encrypted at rest and are never returned in plaintext via UI or API And attempts to export configuration return redacted values for secret fields Given a rotation policy is configured or a manual rotate is triggered When key rotation occurs Then all stored secrets for the connection are re-encrypted without interrupting active operations And subsequent connection attempts use the rotated secrets And an audit entry is recorded for the rotation event When a rotation fails Then the previous secrets remain active, an alert is raised, and the failure is logged

Environment Segregation: Sandbox vs Production

Given I have configured both Sandbox and Production for an ERP connection When I toggle the active environment for a workflow Then the UI clearly indicates the selected environment and its endpoints And only the credentials and endpoints for that environment are used for all operations When Sandbox is selected Then no requests are sent using Production credentials or endpoints When a user without permission attempts to switch environments Then the switch is blocked and a 403/permission error is shown and logged When exporting or viewing configuration Then Sandbox and Production configurations are displayed and stored separately with no cross-contamination

Network Controls: IP Allowlisting and Endpoint Whitelisting

Given an IP allowlist is configured for ERP connections management and status API When a request originates from a non-allowlisted IP Then access is denied with 403 and the event is logged with source IP and user identity Given an endpoint whitelist is configured for the ERP (e.g., /vendors, /bills, /paymentBatches) When a module attempts to call a non-whitelisted ERP endpoint Then the call is blocked before egress, a policy violation is logged, and no request is sent to the ERP When an admin updates the IP allowlist or endpoint whitelist Then changes require proper role permissions and are recorded in the audit log

Connectivity Health: Test Connection, Health Checks, and Status API

Given a connection configuration is saved When I click Test Connection Then the system attempts authentication and a minimal, non-mutating ERP ping And I receive a pass/fail result with latency and any error codes/messages And lastTestedAt and status fields are updated for the connection When credentials are invalid or network is unreachable Then Test Connection reports failure without saving any new tokens Given periodic health checks are enabled When the ERP becomes unavailable or responses degrade Then the connection status transitions to Degraded or Down based on defined thresholds and the reason is captured Given the Status API is queried at GET /connections/{id}/status When the connection is Healthy Then the API returns state=Healthy, isSyncAllowed=true, and timestamps When the connection is Degraded or Down Then the API returns state accordingly, isSyncAllowed=false, and diagnostic details for gating modules

Secrets Governance: RBAC and Audit Trail

Given role-based permissions are configured When a user without Integration Admin permissions attempts to view or edit ERP connection secrets or configuration Then access is denied with 403 and the attempt is logged When an Integration Admin views the connection Then secret fields are masked and plaintext values are never displayed after initial save When an Integration Admin creates, updates, rotates, or deletes credentials Then an immutable audit entry is recorded with actor, timestamp, action, connection id, changed fields (values redacted), and source IP When audit logs are queried for a connection Then all credential lifecycle events are present and uneditable, with filtering by date, actor, and action

Multi-Tenant ERP Connections and Per-Program Routing

Given my organization operates multiple ERP tenants When I create more than one connection for the same ERP type Then each connection can be uniquely labeled and stored with distinct credentials and endpoints Given multiple programs exist in MeritFlow When I assign Program A to ERP Connection 1 and Program B to ERP Connection 2 Then sync operations initiated by Program A use Connection 1 and those by Program B use Connection 2 When a connection mapped to one or more programs is deleted Then deletion is blocked with a message listing dependent programs and remediation options When querying the routing mapping via API Then I receive the list of programId to connectionId mappings for validation

Pre-flight Validation Engine

"As a finance manager, I want to catch posting errors before sync so that we avoid failed transactions and month-end rework."

Description

Implement a configurable rules engine to validate data before ERP sync for vendors, bills/invoices, and payment batches. Validate GL account existence and active status, cost center/project/department validity, open posting periods, currency and tax code compatibility, required vendor fields, duplicate invoice detection, budget/policy thresholds, and attachment presence. Provide per-program rule sets with block/warn actions, human-readable error messages, and downloadable validation reports. Integrate real-time lookups against the ERP and the internal Mapper to surface discrepancies early. Support batch validations, API access, and UI indicators that prevent sync until issues are resolved.

Acceptance Criteria

GL Account and Cost Center Validation Blocks Sync

Given a bill with line items containing GL account codes and cost center codes When the pre-flight validation runs Then the system looks up each GL account and cost center in the ERP and internal Mapper to confirm existence and active status And if any GL account or cost center is missing or inactive, the validation result for that record is Block with a human-readable message referencing the exact code(s) And the Sync to ERP action is disabled for the record until the issue is resolved And each ERP lookup completes within 2 seconds; on timeout or error, the result is Block with a "Lookup failed" message including the source (ERP/Mapper)

Open Posting Period Enforcement

Given a bill or payment batch with a target posting date/period When the pre-flight validation runs Then the system verifies in the ERP that the posting period is open for the company/ledger And if the period is closed or not found, the result is Block with a message including the period identifier And if open, the rule passes with no findings

Currency and Tax Code Compatibility

Given a vendor and bill with specified currency and tax code on each line item When the pre-flight validation runs Then the system verifies that the vendor supports the bill currency per ERP configuration And the system verifies that each line’s tax code is valid for the vendor’s tax jurisdiction and GL account per ERP rules And if any incompatibility is found, the result is Block with a message indicating the incompatible field(s) and expected values And if a tax code is missing where optional by program policy, the result is Warn with a message indicating recommended code

Vendor Required Fields Validation

Given a new vendor to be created during sync When the pre-flight validation runs Then the system confirms presence and format of required fields: Legal Name, Tax ID, Address Line 1, Country, Payment Method And if Payment Method = EFT/ACH, then Bank Name, Account Number (masked), and Routing/IBAN are required and validated against format rules And missing or invalid required fields produce Block results with field-specific human-readable messages And all required fields passing validation produce no findings for this rule

Duplicate Invoice Detection

Given a vendor bill with Vendor ID (or external ref), Invoice Number, Invoice Date, Amount, and Currency When the pre-flight validation runs Then the system checks existing invoices in both MeritFlow and the ERP using normalized Invoice Number (trimmed, case-insensitive) and Vendor And if an exact match on Vendor + Invoice Number exists, the result is Block with a link/reference to the existing record And if a match on Vendor + Invoice Number exists with different amount, the result is Block with a discrepancy message And if a near-duplicate exists (same Vendor and Amount within ±1% within the last 30 days), the result is Warn with a reference to the suspected duplicate

Budget and Policy Threshold Enforcement

Given a program-specific rule set with budget caps and approval thresholds When the pre-flight validation runs on a bill Then the system compares the bill total against remaining budget for the mapped project/department/cost center And if bill total exceeds remaining budget, the result is Block with a message showing bill total, remaining budget, and project code And if bill total exceeds an approval threshold but is within budget, the result follows configured severity (Warn or Block) with a message including the threshold value And all evaluations are logged with rule ID and timestamp for audit

Batch Validation, API, and Validation Report Export

Given a batch submission of up to 1,000 records (vendors, bills, payment batches) across multiple programs When batch pre-flight validation runs via UI or API Then the system validates all records concurrently and returns structured results with rule ID, severity (Pass/Warn/Block), field path, and human-readable message for each finding And overall batch processing completes within 60 seconds under normal load And the UI displays per-record validation badges and disables "Sync to ERP" for any record with Block findings; if only Warn findings and policy allow_warn_sync=true, sync remains enabled with a confirmation prompt And a downloadable CSV and PDF report are available containing record identifiers, entity type, rule IDs, severities, messages, and timestamps And the public API endpoint POST /v1/validation accepts batch payloads and returns HTTP 200 with results; invalid payloads return HTTP 422 with schema errors

Chart of Accounts & Cost Center Mapper

"As a program accountant, I want to centrally map awards to the correct GL accounts and cost centers so that postings hit the right buckets without manual edits."

Description

Deliver an administrative mapping module that links MeritFlow fields (program, fund, grant code, award type) to ERP financial dimensions (GL accounts, cost centers, projects, departments). Provide versioned mapping sets with effective dates, environment awareness (sandbox vs. production), and validation against ERP metadata. Offer bulk CSV import/export, test mode with sample transactions, and suggestions based on historical mappings. Enable overrides at award or line level with conflict detection, approval, and audit logging. Expose REST endpoints for mapping retrieval and updates, and surface mapping warnings directly in pre-flight checks.

Acceptance Criteria

Versioned Mapping Sets with Effective Dates and Fallback

- Given multiple mapping sets with defined effectiveStart and effectiveEnd dates, When resolving a transaction dated within exactly one range, Then the system applies that set to derive GL account, cost center, project, and department. - Given overlapping effective date ranges exist, When attempting to activate a new set, Then the system rejects activation and identifies the conflicting set IDs and date ranges. - Given an active mapping set, When a user attempts to delete it, Then the system blocks deletion and only allows archival to preserve history. - Given a transaction date is outside all active ranges, When resolving mappings, Then the system falls back to the most recent prior effective set if fallback is enabled, else returns a blocking error "No active mapping set for date". - Given an audit request, When retrieving mapping set history for a specific MeritFlow key combination, Then the API returns all versions with createdBy, createdAt, effectiveStart, effectiveEnd, and changeSummary.

Environment-Aware Partitioning and Promotion Workflow

- Given environment=Sandbox, When a mapping is created or edited, Then it is scoped to Sandbox and does not affect Production mappings, and responses include environment=Sandbox. - Given a user with PromoteMappings permission, When promoting a Sandbox set to Production, Then a two-step confirmation with diff preview is required and Production receives a new version ID with identical entries. - Given a user without ProductionEdit permission, When attempting to modify Production mappings, Then the system denies the action (UI disabled, API returns 403) and records the attempt in the audit log. - Given an environment filter is applied, When requesting mappings via UI or GET /mappings, Then only mappings from the selected environment are returned.

Save/Update Mapping with ERP Metadata Validation and Smart Suggestions

- Given an admin enters GL account, cost center, project, and department codes, When saving a mapping, Then the system validates each code against ERP metadata within 5 seconds and blocks save on inactive/nonexistent codes with field-level errors. - Given validation fails, When the user opens the error details, Then ERP descriptions and statuses are displayed for the offending codes. - Given historical mappings exist for the same MeritFlow fields, When the user focuses a code field, Then the system suggests the top 3 ERP codes ranked by frequency over the last 180 days with descriptions. - Given the user accepts a suggestion, When saving, Then the audit log records suggestionAccepted=true, suggestedCode, and rationale if provided. - Given the metadata cache is older than 24 hours, When saving, Then the system refreshes ERP metadata before performing validation.

Test Mode: Sample Transactions and Validation Report

- Given Test Mode is enabled for a mapping set, When the admin runs a sample of at least 50 transactions (or all if fewer exist), Then the system simulates mapping and ERP posting without creating any records in ERP. - Given the test run completes, When viewing results, Then a report displays counts of Pass, Warning, and Error along with itemized diagnostics per transaction. - Given warnings or errors are present, When the admin selects Export, Then a CSV is generated containing transaction identifiers, mapping set version, environment, and diagnostic messages. - Given a performance SLO of 500 transactions per minute, When the sample contains 500 transactions, Then the test completes within 60 seconds at the 95th percentile.

Award/Line-Level Overrides with Conflict Detection, Approval, and Audit Trail

- Given an award or line requires a different GL or cost center, When a user with OverrideCreate permission submits an override, Then the system checks for policy conflicts with the governing mapping set and flags violations with reasons. - Given policy requires approval, When an override is submitted, Then it enters Pending Approval and cannot be applied until approved by a user with OverrideApprove permission. - Given an override is approved, When applied, Then the audit log records award/line ID, old value, new value, reason, requester, approver, timestamps, and optional expiration. - Given an override has an expiration date, When the expiration is reached, Then the system automatically reverts to the mapping set and logs the event. - Given overrides exist for an item, When resolving mappings in pre-flight or sync, Then overrides take precedence and are indicated in UI and API payloads.

Pre-flight Checks Surface Mapping Warnings to Program Managers

- Given pre-flight checks are run for a batch, When mappings resolve to ERP codes that are deprecated or will be inactive within 30 days, Then warnings are shown inline per item and summarized at the batch level. - Given a mapping cannot be resolved, When pre-flight runs, Then the item is blocked with an error and a deep link is provided to open the Mapper with affected fields prefilled. - Given the user fixes mappings with sufficient permissions, When re-running pre-flight, Then prior errors clear without requiring a page refresh and the batch status updates accordingly. - Given warnings remain, When attempting to proceed, Then the system requires explicit acknowledgement and records it in the audit log with user, timestamp, and items acknowledged.

REST API for Mapping Retrieval and Updates with Concurrency and Security Controls

- Given a client with read scope, When calling GET /mappings?environment=Production&effectiveOn=2025-09-01, Then the API returns 200 with mappings filtered by environment and effective date, including pagination and total count. - Given a client updates a mapping, When sending PUT /mappings/{id} with an If-Match ETag, Then the API updates and returns 200 with a new ETag; without a matching ETag it returns 412 Precondition Failed and no changes are saved. - Given RBAC and scopes are enforced, When a token lacks write permissions, Then POST/PUT/PATCH/DELETE return 403 and no mutations occur. - Given per-client rate limits of 100 requests/minute, When the limit is exceeded, Then the API responds 429 with a Retry-After header. - Given invalid payloads, When schema validation fails, Then the API returns 400 with a JSON error list referencing invalid fields and constraints.

Bi-directional Vendor Sync

"As an AP specialist, I want MeritFlow to create or update vendors in the ERP and reflect their status back so that payments can be issued without re-entering data."

Description

Create and update ERP vendor records from MeritFlow grantee profiles with configurable field mappings (legal name, tax ID, address, remit-to, bank details where permitted). Implement de-duplication using tax ID and fuzzy name matching, with a review/merge workflow. Support attachment sync for compliance documents (e.g., W-9/1099) and required custom fields. Propagate ERP vendor IDs and status (active/hold/inactive) back to MeritFlow to gate payments. Respect ERP validations and approval workflows, and run in sandbox dry-run mode before production. Maintain full auditability and rollback of pending changes if ERP rejects updates.

Acceptance Criteria

Configurable Field Mapping for Vendor Sync

Given an admin configures vendor field mappings between MeritFlow and the ERP (legal name, tax ID, address, remit-to, bank details where permitted, and required custom fields) When the mapping is saved Then the system validates that all ERP-required fields have mappings or defaults and returns a success state And unmapped optional ERP fields are skipped without error And a preview shows resolved mapped values for at least 5 sample grantees And bank details are included only when "Bank Data Permitted" is enabled and the user has the "Bank Data Admin" role And the saved mapping is versioned with timestamp, editor, and change summary in the audit log

Create New Vendor in ERP from Grantee Profile

Given a grantee profile contains all mapped required fields and passes de-duplication checks When "Create Vendor in ERP" is triggered from MeritFlow Then an ERP vendor record is created with mapped fields and required attachments per configuration And the ERP Vendor ID is returned and stored in MeritFlow within 30 seconds And the MeritFlow vendor link shows status "Created" or "Pending ERP Approval" as returned by the ERP And request/response metadata with correlation ID is captured in the audit log

Update Existing ERP Vendor from MeritFlow Edits

Given a MeritFlow vendor is linked to an ERP Vendor ID When mapped fields are edited in MeritFlow and "Sync Updates" is triggered Then only changed fields are sent to the ERP And ERP validation or approval errors are returned with field-level messages And no partial updates persist in the ERP if any error occurs (transactional all-or-nothing) And if ERP approval is required, MeritFlow displays "Pending ERP Approval" until confirmation is received And if the ERP rejects the change set, MeritFlow restores prior synchronized values and logs the rejection with ERP error codes

Vendor De-duplication and Review/Merge Workflow

Given a vendor create or link is initiated When an exact Tax ID match or fuzzy legal-name similarity of 0.85 or higher is detected in ERP or MeritFlow Then auto-create is blocked and the user is presented with candidate matches and match scores And the user can select Link, submit a Merge request, or Continue with Override if they have "Vendor Override" permission And a merge request captures field-level source-of-truth selections and requires "Vendor Merge Approver" approval And upon link or approved merge, no duplicate vendor is created in ERP and the action is fully auditable

Compliance Document Attachment Sync

Given current W-9/1099 and other required compliance documents are attached to the grantee profile When a vendor create or update is synchronized Then attachments are transmitted to the ERP via API over TLS 1.2+ and associated to the ERP Vendor ID And file type, size, and required metadata are validated before transmission And if the ERP rejects an attachment, the vendor sync fails and rolls back with a clear error shown to the user And subsequent uploads create new attachment versions in both systems with timestamps and uploader identity

ERP Vendor ID and Status Back-Propagation with Payment Gating

Given ERP webhooks or polling are configured When the ERP assigns/updates the Vendor ID, status (Active/Hold/Inactive), or mapped vendor fields (e.g., address, remit-to) Then MeritFlow updates the linked record within 5 minutes And payment workflows in MeritFlow are blocked when status is Hold or Inactive with an explanatory message And if a field is owned by MeritFlow per mapping ownership, a conflicting ERP change creates a review task instead of auto-applying And all inbound changes record source, timestamp, and ERP user/system in the audit log

Sandbox Dry-Run Pre-flight Check

Given Integration Mode is set to Sandbox Dry-Run When a user runs a pre-flight check for a batch of N vendors Then no records or attachments are persisted in the ERP And a downloadable report lists each vendor with Pass/Fail, field-level validation messages, and ERP error codes where applicable And batch summary includes counts for Pass, Fail, Skipped and average/total simulated processing time And no ERP Vendor IDs or statuses are stored on MeritFlow records as a result of the dry run

Bill/Invoice & Payment Batch Sync

"As a treasury analyst, I want approved awards to flow into ERP as bills and payment batches so that disbursements are timely and controlled."

Description

Generate ERP AP bills/invoices from approved awards and scheduled disbursements, with support for line-item detail, attachments (award letters, approvals), tax/withholding rules, and multi-currency. Group transactions into payment batches by payment date, funding source, bank account, or program rules. Ensure idempotency using deterministic keys to prevent duplicates, and capture ERP document numbers back into MeritFlow for traceability. Allow manual or scheduled pushes, partial payments, voids/cancellations, and re-syncs. Enforce permissions and integrate with pre-flight checks and the Mapper. Provide success/failure receipts and reconcile status updates from ERP back to award records.

Acceptance Criteria

Manual Bill Sync with Line Items and Attachments

Given an approved award with scheduled disbursements that pass pre-flight checks (vendor resolvable/creatable, GL accounts and cost centers mapped by the Mapper, tax/withholding rules valid) and a user with Finance Sync permission selects them for push When the user triggers "Push to ERP → Bills" Then one AP bill/invoice per configured grouping is created in the ERP with line items matching MeritFlow (description, quantity, unit amount, GL account, cost center, program/project, currency) And tax/withholding is represented per ERP mapping without altering intended net amounts And attachments (award letters, approvals) are transmitted and linked on the ERP document, and the ERP document links are stored on the corresponding disbursement in MeritFlow And items that fail pre-flight are blocked from push with actionable error reasons shown to the user And a success receipt is generated containing count, ERP document numbers, deterministic keys, and start/end timestamps; failures include error code and message

Scheduled Payment Batch Sync by Date and Funding Source

Given a configured sync schedule and eligible disbursements in status "Ready to Pay" with payment date, funding source, and bank account mappings present When the scheduler runs within the configured window Then ERP payment batches are created grouped by payment date + funding source + bank account + program rules And batch totals equal the sum of included disbursements, with currency respected per batch And only disbursements passing pre-flight checks are included; skipped items are logged with reasons And ERP batch identifiers/numbers are captured back to MeritFlow and associated with each included disbursement And a batch summary receipt is stored containing batches_created, items_included, items_skipped, total_amounts_by_currency, and timestamps

Idempotent Re-sync Prevents Duplicates

Given each bill/payment payload produces a deterministic key composed of award_id + disbursement_id + vendor_external_id + currency + gross_amount + scheduled_payment_date + line_item_hash And an ERP document already exists for that key When a manual or scheduled push for the same items is re-run Then no new ERP bill/payment is created, and the existing ERP document is re-linked if necessary And the receipt records the operation as idempotent (created=0, linked=1) with the deterministic key and ERP document number And if the ERP document is missing (e.g., manually deleted), the push creates a new document using the same key and updates MeritFlow with the new ERP document number

Multi-Currency and Tax/Withholding Application

Given an award/disbursement currency may differ from the ERP base currency and a configured exchange rate source and effective date policy When bills are created in the ERP Then exchange rates are applied per configuration, amounts are rounded to the currency minor unit, and line totals plus tax/withholding equal the document total And withholding/tax is posted to the correct GL accounts per mapping and shown as separate lines or fields as required by the ERP And the payable (net) amount matches MeritFlow’s calculated net within the currency minor unit tolerance

ERP Document Number Capture and Traceability

Given ERP returns document identifiers upon successful creation of bills and payment batches When a sync completes successfully Then MeritFlow stores ERP document number, document type, ERP link/URL (if available), document date, and current ERP status on the related award/disbursement/batch records And these fields are visible on the award and disbursement detail views and are searchable via global search and filters And an immutable audit log entry is recorded capturing who initiated the sync (user or scheduler), timestamp, deterministic key, and ERP document number

Partial Payments and Balance Management

Given a synced bill is partially paid in the ERP When status reconciliation runs from ERP to MeritFlow Then MeritFlow updates the paid amount, remaining balance, and payment history on the associated disbursement/award And subsequent syncs exclude already paid amounts and only include the remaining balance according to schedule and rules And receipts for reconciliation include the payment reference(s), amounts by currency, and updated balances

Voids/Cancellations and Status Reconciliation

Given a user with Finance Admin permission voids/cancels a synced bill or payment batch in MeritFlow, or the document is voided in the ERP When the next sync/reconciliation cycle runs Then the corresponding MeritFlow records are updated to Voided/Cancelled with ERP reason/status, and further pushes against the voided document are blocked And any remaining unpaid scheduled amounts are re-opened for re-sync per program rules using a new deterministic key version And an audit log captures the actor, timestamp, action (void/cancel), affected deterministic key(s), and ERP confirmation; users without required permission cannot initiate void/cancel

Sync Orchestrator, Idempotency & Retry Queue

"As a platform engineer, I want a resilient sync pipeline with retries and idempotency so that ERP integrations remain reliable under load and outages."

Description

Build an event-driven orchestrator to manage ERP sync jobs with configurable priorities, rate limiting, and concurrency per ERP connector. Implement idempotency keys and deduplication across retries and replay scenarios. Provide automatic retries with exponential backoff, a dead-letter queue for manual intervention, circuit breakers for ERP outages, and visibility timeouts. Support both webhook-driven callbacks and scheduled polling for reconciliation. Expose operational metrics, tracing, and structured logs for observability, and allow per-program schedules and blackout windows to avoid month-end closures.

Acceptance Criteria

Scheduling, Rate Limits, Per-Connector Concurrency, and Blackout Windows

Given connector A has High priority jobs and connector B has Normal priority jobs queued, When workers pull from the queue, Then High priority jobs are dequeued before Normal, with FIFO ordering within the same priority. Given per-connector concurrency C=3 and rate limit L=120 calls/min for connector A (configurable), When jobs execute, Then no more than 3 concurrent jobs run for A and outbound calls do not exceed 120/min; excess jobs remain queued. Given a program with an active blackout window (e.g., 2025-08-30 00:00–2025-09-02 23:59 local), When a job becomes eligible during the blackout, Then the job remains queued, annotated paused_due_to_blackout, and is automatically scheduled immediately after the window ends. Given allowed schedule windows (e.g., weekdays 06:00–22:00 local), When outside the window, Then new executions do not start; when inside, eligible queued jobs start subject to limits. Then metrics expose queue_depth, wait_time_ms, rate_limit_utilization_pct, and paused_blackout_count per connector and program.

Idempotency Keys and Deduplication Across Retries and Replays

Given multiple enqueue attempts for the same operation share the same idempotency_key within a 30-day retention window (configurable), When processed, Then exactly one execution occurs and subsequent attempts are acknowledged as duplicates with no ERP calls made. Given a retry of a previously failed attempt with the same idempotency_key, When retried, Then no duplicate vendors/bills/payments are created; ERP requests include the idempotency token if supported by the ERP. Given a replay request for a completed idempotency_key, When executed, Then the prior result is returned and no side effects occur. Given a crash and restart, When the same idempotency_key appears, Then deduplication persists and prevents duplicate execution (durable store).

Exponential Backoff Retries and Dead-Letter Queue Handling

Given a transient error (HTTP 429/5xx or timeout) from the ERP, When a job fails, Then it retries with exponential backoff and full jitter starting at 2s, doubling up to 2m max backoff, with max_attempts=5 (all configurable). Given a non-retryable error (HTTP 4xx excluding 429) or validation failure, When processing fails, Then the job is not retried and is moved immediately to the dead-letter queue (DLQ) with error_code and last_error captured. Given a job reaches max_attempts without success, When the last retry fails, Then it is moved to the DLQ with attempt_count, first_failure_at, last_failure_at, and correlation_ids stored; dlq_inserts_total metric increments. Given a user triggers Replay on a DLQ item, When replayed, Then the job is re-enqueued with a new job_id while preserving the original idempotency_key and context; attempt_count resets to 0.

Circuit Breaker Behavior During ERP Outages

Given a connector’s failure rate >=50% over a rolling 1-minute window with >=20 requests or 10 consecutive failures (configurable), When evaluated, Then the circuit opens for 5 minutes. While open, When a job targets that connector, Then the job is not executed and is re-queued with next_attempt_at set to the next half-open time; no outbound ERP calls are made. When cooldown elapses, Then the circuit enters half-open and allows up to 5 probe requests; if success rate of probes >=80% the circuit closes, else it re-opens for another cooldown. Then metrics expose circuit_state{connector} and circuit_open_total; logs record state transitions with reasons.

Queue Leasing and Visibility Timeout Guarantees

Given a worker leases a job with visibility_timeout=5m (configurable), When leased, Then the job becomes invisible to other workers for the lease duration. Given the worker sends heartbeats before timeout, When a heartbeat is processed, Then the lease extends by the configured increment without creating duplicate leases. Given the worker crashes or fails to ack, When the visibility timeout elapses, Then exactly one re-delivery occurs and no two workers process the same job concurrently (mutual exclusion). Given a job is acknowledged, When the ack is persisted, Then the job is removed permanently and will not be delivered again.

Webhook Callbacks and Scheduled Polling for Reconciliation

Given an ERP connector with webhooks enabled, When a signed callback is received, Then the signature is verified, the payload is deduplicated by event_id, and the related job status is updated within 5s; invalid signatures are rejected with 401 and not processed. Given polling is enabled at interval P=10m per program (configurable), When a poll runs, Then the orchestrator requests changes since last_checkpoint and reconciles statuses for vendors/bills/payments, respecting rate limits. Given a webhook is missed or fails temporarily, When the next poll runs, Then missed updates are reconciled without duplicate side effects. Then per-program settings allow webhook, polling, or hybrid mode; mode changes take effect within one interval.

Observability: Metrics, Tracing, and Structured Logs

Given the orchestrator is running, When scraping /metrics, Then Prometheus metrics include queue_depth, in_flight, success_total, failure_total, retry_total, dedup_hits_total, dlq_size, processing_latency_ms{p50,p95,p99}, erp_latency_ms, circuit_state, rate_limit_utilization_pct, and blackout_paused_total. Given a job is processed end-to-end, When viewing traces, Then a single distributed trace exists with spans for enqueue, dequeue, ERP call, retry/backoff (if any), and ack; spans carry trace_id, program_id, connector_id, job_id, and idempotency_key via W3C Trace Context (OpenTelemetry compliant). Given INFO/ERROR logs are emitted, When inspecting logs, Then entries are structured JSON with fields timestamp, level, program_id, connector_id, job_type, job_id, idempotency_key, attempt, outcome, error_code, and latency_ms; sensitive fields are redacted and no PII payloads are logged. Given SLOs are defined, When computing rolling 30-day availability, Then success_rate >= 99.5% and p95_processing_latency <= 2m for standard-priority jobs (values configurable and emitted as metrics).

Reconciliation Dashboard & Audit Trail

"As a controller, I want a reconciliation dashboard and complete audit trail so that we can prove compliance and quickly resolve discrepancies."

Description

Provide a real-time dashboard and API to track the lifecycle of vendors, bills, and payment batches across MeritFlow and the ERP. Show per-record status, last sync time, ERP IDs, and a diff view highlighting field discrepancies. Allow authorized users to resolve conflicts, re-run syncs, or void transactions with appropriate approvals. Maintain an immutable audit trail of who changed what and when, including payload snapshots and ERP responses, with export to CSV/JSON and webhook notifications for failures. Include SLA metrics, saved views, permissions, and configurable data retention to meet compliance requirements.

Acceptance Criteria

Real-Time Reconciliation Dashboard & API Visibility

Given an authorized user views the Reconciliation Dashboard And vendors, bills, and payment batches exist with ERP linkage And the system is connected to the ERP When the user filters by entity type, program, status, or date range Then each row displays current MeritFlow status, ERP status, last sync time (UTC), and ERP external IDs And the dashboard reflects ERP changes within 60 seconds of change detection And the public API endpoint for reconciliation returns equivalent results with pagination, sorting, and identical filters And 95th percentile response time for dashboard and API is ≤ 2 seconds for up to 50,000 records And columns are configurable per user session without affecting other users

Discrepancy Diff View Highlighting

Given a record has at least one differing field between MeritFlow and the ERP When the user opens the Diff view for that record Then the system highlights mismatched fields with side-by-side MeritFlow vs ERP values and last-updated source And null vs empty-string differences are normalized according to mapping rules And derived/mapped fields are hidden by default and can be toggled on And the user can copy either value to clipboard or select a side for potential resolution (pending confirmation/approval)

Conflict Resolution, Re-run Sync, and Void with Approvals

Given a record is in conflict or has a failed sync And the user holds the Resolve Sync Conflicts permission When the user selects Re-run Sync Then pre-flight validations run, the ERP sync is re-attempted, and a new audit entry is created with request/response payloads And on success, the record status and ERP IDs update within 60 seconds across dashboard and API When the user selects Accept ERP Value or Push MeritFlow Value Then a comment is required and a versioned change is created And if the action requires approval, a two-step approval workflow is initiated and must be approved by a Finance Approver before execution And users lacking required permissions cannot initiate these actions and receive a clear authorization error When the user requests Void Transaction Then an approval is required, a reason is captured, the ERP void call is executed, outcome is recorded, and on failure a Failure webhook is emitted

Immutable Audit Trail with Payload Snapshots

Given any reconciliation action, sync attempt, approval, export, or configuration change occurs When the action is executed Then an append-only audit entry is written with timestamp (UTC), actor, action type, entity type and ID, before/after values or payload snapshots, ERP request/response, correlation IDs, and source IP And audit entries cannot be edited or deleted via UI or API; modification attempts are rejected with 403 and logged And each audit entry includes a sequential ID and checksum/hash to detect tampering And audit entries are searchable/filterable by date range, entity, actor, action, and correlation ID And retention is enforced such that after the configured period, sensitive payload fields are redacted while the audit entry metadata remains

Audit Trail Export to CSV/JSON

Given a user with Export Audit permission requests an export When the user specifies date range, entity types, fields, and selects CSV or JSON format Then an export is generated within 2 minutes for up to 1,000,000 rows or streamed progressively for larger sets And CSV output is UTF-8 with headers and RFC 4180 quoting; JSON output is NDJSON (one JSON object per line) And payload snapshots can be included or redacted by option; redacted fields display as **** And exports respect row-level permissions and retention; excluded records are omitted And the export job, parameters, row count, file size, and requester are recorded in the audit trail And if results exceed the configured maximum, the user is prompted to refine filters or receives a segmented export

Failure Webhook Notifications with Retry and Signature

Given a sync failure, conflict creation, void failure, or SLA breach occurs And at least one webhook endpoint is configured and enabled When the event is generated Then a POST is sent containing event_type, entity_type, entity_id, correlation_id, timestamp (UTC), and error_details where applicable And the request includes an HMAC-SHA256 signature header using the shared secret And non-2xx responses trigger exponential backoff with jitter up to 10 attempts or 24 hours, whichever comes first And delivery attempts, responses, and signatures are logged and visible in a delivery log with manual redelivery option And webhook payloads exclude PII by default unless explicitly configured to include

SLA Metrics and Saved Views with Retention Enforcement

Given the dashboard is loaded When the user opens the SLA panel Then metrics display sync success rate (24h and 7d), average end-to-end sync latency, oldest pending sync age, and failure rate by entity And configurable thresholds drive green/amber/red indicators and alert banners When the user creates a saved view (filters, columns, sort) Then the view can be named, made private or shared to roles, and later loaded; only the owner or admins can modify or delete it And changes to saved views and SLA thresholds are permission-gated and recorded in the audit trail And data retention is configurable per environment (e.g., 90–730 days) and enforced by nightly purge jobs that redact payloads while preserving audit metadata, with purge actions logged

Payee Verify

Guided W‑9/W‑8 collection, IBAN/ACH validation, and optional micro-deposit verification. Auto-detect duplicates, enforce regional compliance, and store sensitive details in a permissions-tight vault—cutting payout failures and audit risk while reducing back-and-forth with grantees.

Requirements

Dynamic Tax Form Wizard

"As a grant coordinator, I want a guided tax form collection that adapts to the payee’s situation so that I collect the right forms with fewer errors and avoid back-and-forth."

Description

A guided, conditional flow that determines whether the payee must submit W‑9 or W‑8 variants based on citizenship, entity type, and payment context; includes inline validation of TIN formats, legal name matches, and address normalization. Produces IRS‑compatible outputs as structured data and generated PDFs, captures digital signature/attestation with timestamp and IP, supports save/resume, prefill from prior submissions, and revision history. Maps normalized tax data to MeritFlow’s payee model and writes artifacts to the secure vault with referential links for audit.

Acceptance Criteria

Form Selection Logic: W-9 vs W-8 Variant Determination

- Given a payee indicates citizenship/residency, entity type, and payment context, when the wizard evaluates responses, then it selects the correct form: W-9 (US persons), W-8BEN (foreign individual), W-8BEN-E (foreign entity), W-8ECI (ECI income), W-8EXP (foreign tax-exempt), or W-8IMY (intermediary). - Given the user changes a prior answer affecting form selection, when reevaluated, then the wizard updates the chosen form within 500 ms and prompts to reconfirm any impacted answers. - Given form selection is made, when the decision is finalized, then an audit record stores the inputs used, chosen form, rules version, timestamp, and user ID.

TIN and Legal Name Validation

- Given a W-9, when a TIN is entered, then it must match valid SSN/EIN/ITIN formats and entity-type rules (individual: SSN/ITIN; business: EIN); otherwise block submission with a specific error. - Given a W-8 where FTIN is required by country, when FTIN is omitted, then the wizard requires an explanation per IRS guidance and blocks submission until provided or a permitted exception is selected. - Given legal name and TIN are entered, when normalized (case/punctuation-insensitive), then the name must conform to the chosen entity type (e.g., individual vs business) and match Payee legal name on file or require explicit attestation override capturing reason. - Given sensitive values are entered, when the form is saved or submitted, then TIN values are never persisted outside the secure vault and are masked in UI outside entry fields.

Address Normalization and Validation

- Given a US address is entered, when validated, then ZIP+4, city, and state are normalized to USPS standards or a correction suggestion is shown; submission is blocked until a valid or explicitly confirmed-as-entered address is selected. - Given a non-US address is entered, when validated, then country must be ISO 3166-1 alpha-2, region/province standardized where applicable, and postal code validated against country-specific patterns; otherwise show errors and block submission. - Given normalization occurs, when the record is persisted, then both normalized components and the original raw input are stored in the revision history. - Given address validation calls external services, when invoked, then responses return within 2 seconds or fall back to local format checks with user notification.

IRS-Compatible Outputs: Structured Data and PDF Generation

- Given a completed and signed form, when submitted, then a structured JSON payload is produced conforming to the configured IRS schema version for the selected form with 100% mapped required fields. - Given structured data exists, when a PDF is generated, then the official IRS template for the current tax year is filled and flattened, values match the structured data exactly, and a SHA-256 hash of the PDF is stored. - Given the structured payload and PDF, when a round-trip test is executed, then rehydrating the UI from JSON regenerates an identical PDF (hash match) and field set. - Given artifacts are produced, when stored, then file names follow {payeeId}_{formType}_{YYYYMMDD}_v{rev}.pdf and .json conventions.

Digital Signature and Attestation Capture

- Given the final review step, when the user signs, then the system requires attestation text acknowledgement, typed name, and signature intent checkbox before enabling submission. - Given a signature is captured, when persisted, then timestamp (UTC ISO 8601), public IP, user ID, and the attestation text version are bound immutably to the submission revision. - Given a signed submission, when any field is edited afterward, then the prior version remains read-only and a new unsigned revision is created requiring a new signature.

Save/Resume and Prefill from Prior Submissions

- Given a user is completing the wizard, when typing or leaving a field, then the draft auto-saves at least every 10 seconds and on field blur; a manual Save action is also available. - Given a saved draft exists, when the user resumes via the portal, then the wizard restores to the last step with all previously entered data within 2 seconds. - Given an accepted prior submission of the same form exists within 24 months, when starting a new submission, then eligible fields are prefilling; TIN values are only prefilling if policy and permissions allow, otherwise re-entry is required. - Given prefilled data, when submitting, then the system requires re-attestation even if no changes were made and highlights any modified fields since prefill.

Revision History, Payee Model Mapping, and Secure Vault Storage

- Given any save or submit, when changes occur, then a new immutable revision is recorded with actor, timestamp, reason (if provided), and a field-level diff. - Given normalized tax data, when persisted, then it maps to the payee model fields (e.g., taxClassification, formType, tinType, last4Tin, country, normalizedAddress, signatureMetadata) and passes schema validation. - Given submission artifacts, when stored, then structured data and PDFs are written to the permissions-restricted vault and referenced on the payee record by artifact IDs. - Given role-based access controls, when a user without sensitive access views the record, then TIN is masked (e.g., ***-**-1234) and PDFs render with masked TIN; users with access can retrieve full values. - Given an audit request, when querying by payee and date range, then all revisions and artifact links return within 2 seconds; encryption in transit (TLS 1.2+) and at rest (AES-256) are verified by configuration tests.

Bank Account Validation & Micro-Deposits

"As a program manager, I want to validate bank details and verify ownership so that payouts don’t fail and funds go to the correct payee."

Description

Syntactic and rules-based validation for ACH and IBAN, including routing checksum, IBAN mod‑97, country-specific length/format rules, and optional SWIFT/BIC capture; supports masked preview and account fingerprinting. Offers optional micro-deposit verification workflow: triggers two deposits via payment rail provider, tracks status, sends notifications, and lets payees confirm amounts in-portal with retry/lockout and expiration controls. Provides sandbox mode, configurable thresholds, and clear error messaging to reduce payout failures.

Acceptance Criteria

ACH Routing and Account Number Validation

- Given a US payee enters a 9-digit routing number with spaces or dashes, When the field loses focus or on submit, Then the value is normalized to digits-only and validated using the ABA checksum; invalid values are rejected with the field error "Invalid routing number". - Given a US payee enters an account number, When the form is validated, Then the value must be 4–17 digits, numeric-only after normalization; otherwise show the field error "Invalid account number". - Given routing and account numbers both pass validation, When the user submits, Then the bank account is marked "Valid: ACH" and saved for further verification steps.

IBAN Validation with Country Rules and BIC Capture

- Given a payee enters an IBAN with mixed case and spaces, When the field loses focus or on submit, Then the IBAN is uppercased, spaces removed, and country code extracted. - Given a normalized IBAN, When validated, Then it must match the country-specific length/pattern and pass the mod-97 check (result = 1); failures show "Invalid IBAN for {country}". - Given the organization requires BIC (globally or for the IBAN country), When the user submits, Then the BIC field is required and must be 8 or 11 alphanumeric uppercase characters; failures show "Invalid BIC". - Given IBAN and (if required) BIC are valid, When submitted, Then the bank account is marked "Valid: IBAN" and saved for further verification steps.

Masked Preview and Account Fingerprinting with Duplicate Detection

- Given a bank account passes validation, When shown in UI, Then only a masked preview is displayed (ACH: account ****{last4}; IBAN: {country}••••{last4}); full values are never rendered client-side. - Given a bank account is saved, When processing, Then the system generates a non-reversible fingerprint from normalized bank details to enable duplicate detection. - Given a new submission matches an existing fingerprint within the same organization, When saving, Then the save is blocked and the user sees "Bank account already on file" with guidance to use the existing record. - Given a user lacks vault-read permission, When viewing the record, Then only masked values are visible; attempts to access full values are denied and logged.

Micro-Deposit Verification Workflow with Retries, Lockout, and Expiration

- Given micro-deposits are enabled, When a new validated bank account is submitted, Then two micro-deposits are initiated via the provider and status becomes "Pending deposits". - Given provider webhooks/polls confirm deposits posted, When received, Then status updates to "Ready to verify" and the payee is notified via email and in-app message. - Given the payee enters two amounts within the confirmation window (default 14 days), When they match provider amounts exactly, Then status becomes "Verified"; future edits to bank details require re-verification. - Given the payee enters incorrect amounts, When submitted, Then remaining attempts decrement and are shown; after max attempts (default 3), verification is locked for 24 hours by default and the payee is notified. - Given the confirmation window expires without successful verification, When the payee or admin attempts to continue, Then status is "Expired" and a re-initiation option is provided; previous deposits are invalidated. - Given provider initiation fails, When the attempt is recorded, Then status is "Failed to initiate" and an admin notification is sent with the error code.

Clear Error Messaging and Accessibility

- Given any validation failure (ACH, IBAN, BIC, micro-deposits), When shown to the user, Then messages are field-level, human-readable, localized, and do not reveal full sensitive values (only masked tails). - Given form validation fails, When the page renders, Then focus moves to the first invalid field, an aria-live region announces the error summary, and each control includes descriptive help text. - Given multiple errors occur, When displayed, Then errors are listed in a summary with deep links to each field and are keyboard-navigable.

Sandbox Mode for Validation and Micro-Deposit Simulation

- Given sandbox mode is enabled for the organization/environment, When bank details are submitted, Then ACH/IBAN validation runs locally and micro-deposits are simulated with deterministic amounts per fingerprint; no external provider calls are made. - Given sandbox mode is active, When viewing the UI and notifications, Then a visible "Sandbox" badge is shown and messages are clearly labeled as test; vault data is flagged as test data. - Given test automation needs status control, When using sandbox APIs, Then engineers can force statuses (e.g., pending, ready, verified, expired, lockout) via documented hooks.

Admin-Configurable Thresholds and Controls

- Given an admin opens verification settings, When configuring, Then they can set: max attempts (1–5), lockout duration (1–72 hours), confirmation window (1–30 days), micro-deposit amount range ($0.01–$0.99), and BIC requirement toggles by country or globally. - Given settings are saved, When validated, Then out-of-range or conflicting values are rejected with inline errors; successful changes are audited with timestamp and actor. - Given settings change, When new verification sessions start, Then they use the new values; existing sessions continue with the prior values; UI copy reflects current settings.

Duplicate Payee Detection

"As a finance admin, I want automatic duplicate detection so that we don’t create multiple payee records that lead to duplicate or misdirected payments."

Description

Real-time and batch deduplication using fuzzy matching on legal name, TIN, email domain, and bank fingerprint; surfaces a confidence score with preview of potential matches across programs and cycles; allows merge, link, or ignore with reason codes; enforces one-active-bank-account policy per payee when configured; provides a reviewer queue, false-positive suppression, and full audit trail of dedup decisions.

Acceptance Criteria

Real-time duplicate suggestion during payee onboarding

Given a user enters or edits legal name, TIN, email, and bank details for a new payee, When the user blurs the last required field or opens the review step, Then the system runs real-time deduplication and returns candidate matches within 800 ms at the 95th percentile. Given candidate matches exist, Then the UI displays up to 5 highest-confidence candidates sorted by confidence descending, each with: payee ID, program, cycle, matched-attributes highlights, and a numeric confidence score between 0.00 and 1.00 rounded to two decimals. Given at least one candidate meets or exceeds the configurable threshold (default 0.80), Then a "Possible duplicate" banner appears and the actions Merge, Link, and Ignore are enabled per candidate. Given the user selects Ignore on a candidate, Then a reason code from a managed list is required and an optional note may be provided; proceeding without a reason is blocked. Given duplicate candidates are shown, Then sensitive fields are masked (e.g., TIN and bank account shown as last-4, bank fingerprint only) and no full account numbers are displayed.

Batch deduplication on import and scheduled job

Given an admin uploads or syncs a batch of payees or a nightly job is triggered, When batch dedup runs, Then it applies the same fuzzy matching rules used in real-time across programs and cycles and generates a reviewer queue item for each candidate pair at or above the batch threshold (configurable, default 0.85). Then the job produces a summary with counts: total payees scanned, candidate pairs created, auto-merged (if auto-merge is enabled), queued for review, suppressed, and errors, and persists the summary with a timestamp. Given the same batch is retried, Then the process is idempotent and does not create duplicate queue items for unchanged pairs; previously suppressed pairs remain suppressed. Given a batch exceeds 10,000 payees, Then progress is checkpointed at least every 1,000 records and the job can resume from the last checkpoint after a failure. Given the batch completes, Then a downloadable CSV of candidate pairs with IDs, confidence, and statuses is available to admins.

One-active-bank-account enforcement on new account activation

Given the one-active-bank-account policy is enabled for the tenant, When a user attempts to activate a bank account for a payee that already has an active account, Then the activation is blocked with a clear message and options to deactivate the existing account or request an override. Given a user with the permission "BankPolicy.Override" attempts the activation, Then they may proceed only after selecting an override reason code and entering a note; the previous account is automatically deactivated or the user is prompted to choose which account remains active, and the decision is recorded. Given two payees are merged, Then the survivor payee ends with no more than one active bank account; if both had active accounts, the system requires the reviewer to select the active one before completing the merge.

Reviewer queue triage and assignment for potential duplicates

Given candidate pairs exist, When a reviewer opens the Duplicate Review queue, Then items are listed with columns: pair ID, payee names, confidence, program, cycle, age, and status; default sort is confidence descending and secondary sort by age descending. Then reviewers can filter by program, cycle, confidence range, status (New, Pending, Ignored, Linked, Merged), assignee, and date range; filters combine with AND logic and can be saved per user. Given the reviewer selects one or more items, Then they can bulk-assign to themselves or others; only users with the permission "Dedup.Review" can take action. Given a reviewer opens an item, Then a side-by-side view shows both records with matched fields highlighted and actions Merge, Link, Ignore; keyboard shortcuts perform these actions and move to the next item. Then taking any action updates the item status, removes it from the New list, and records the action with user and timestamp.

False-positive suppression after Ignore with reason

Given a reviewer selects Ignore with reason "Not a duplicate" on a candidate pair, Then that exact pair is suppressed from both real-time suggestions and the review queue for 90 days or until material data changes (legal name, TIN, domain, or bank fingerprint) on either record, whichever comes first. Given suppression is active, Then suppressed pairs do not reappear unless the reviewer toggles "Show suppressed" (admins only) or the suppression TTL expires or data changes. Given an admin views suppressed pairs, Then they can lift suppression early with a reason code; the lift is logged and the pair re-enters the queue if still above threshold. Then suppression stores: pair key, reason code, note, actor, created at, TTL, last data hash used for match, and lifted at (if applicable).

Comprehensive audit trail for dedup actions and outcomes

Given any dedup action occurs (Merge, Link, Ignore, Auto-merge, Threshold change affecting auto-merge), Then an immutable audit record is created capturing: actor (user/service), timestamp (UTC), action type, source (Real-time or Batch), involved payee IDs, selected survivor (for merges), previous and new link relationships, reason code, optional note, confidence score at decision, and masked sensitive fields. Given an auditor opens a payee, Then a chronological audit timeline is visible with filters by action type and date; entries are read-only and can be exported to CSV for a date range. Given an API client queries audit logs by payee ID or date range, Then the API returns paginated results with the same fields within 2 seconds for the 95th percentile for pages up to 500 items. Given a payee was merged, Then lookups by the non-survivor ID resolve to the survivor record via an alias/link and an audit entry records the resolution mapping.

Regional Compliance Rules Engine

"As a compliance officer, I want region-aware checks that enforce the right documents and consents so that we meet regulatory obligations consistently."

Description

Configurable rules engine that auto-enforces regional requirements (e.g., US W‑9 vs. non‑US W‑8 variants, additional declarations for scholarship vs. services, GDPR consent for EEA data subjects, and data masking for restricted fields) and blocks submission until mandatory elements are satisfied. Supports versioned rule sets, effective-dates, environment-based configurations, and an admin UI to toggle requirements by jurisdiction and program. Generates compliance checklist artifacts per payee for audits.

Acceptance Criteria

Regional Tax Form Enforcement (US W-9 vs Non-US W-8)

Given payee country = United States, When the payee enters tax information, Then the system requires W-9 fields (name, TIN, address) and certification, validates TIN pattern (SSN/EIN), and blocks submission until all mandatory fields pass validation. Given payee country ≠ United States AND tax classification = Individual, When tax information is requested, Then the system requires W-8BEN fields and blocks submission until all required fields are completed and validated. Given payee country ≠ United States AND tax classification = Organization, When tax information is requested, Then the system requires W-8BEN-E fields and blocks submission until all required fields are completed and validated. Then validation messaging enumerates missing/invalid items and focuses the first failing field.

Program Type-Specific Declarations (Scholarship vs Services)

Given program type = Scholarship/Stipend, When the payee completes compliance steps, Then the system requires a “no services rendered” declaration and beneficial owner attestation where applicable, and blocks submission until acknowledged. Given program type = Services/Contractor, When the payee completes compliance steps, Then the system requires a business status declaration and, for US payees, backup withholding certification, and blocks submission until acknowledged. Then all declarations are stored with timestamp, user identity, and policy version and are included in the compliance checklist.

GDPR Consent Capture for EEA Data Subjects

Given payee country is in the EEA or the payee self-identifies as an EEA data subject, When personal data collection begins, Then the system displays GDPR consent with specific purposes and requires explicit opt-in (unchecked by default) before proceeding. When consent is given, Then the system stores consent record (timestamp, IP, purposes, policy version) and includes the record in the compliance checklist. When consent is withdrawn, Then further processing of non-essential personal data is blocked, affected workflows surface a “consent withdrawn” error to admins, and a revocation record is logged.

Restricted Field Data Masking and Role-Based Access

Given a user without Sensitive Data permission views a payee, When restricted fields (e.g., SSN/TIN, bank account, routing, IBAN) are displayed, Then values are masked except last 4 and are masked in UI, exports, and API responses. Given a user with Sensitive Data permission, When they choose Reveal, Then full values are shown for max 15 minutes in-session after MFA and an audit event (who, when, what) is recorded. Then restricted values are stored only in the vault (tokenized in the app DB), are encrypted at rest, and are redacted from application logs.

Rule Set Versioning and Effective-Date Auto-Selection

Given multiple effective-dated rule sets exist, When a payee starts Payee Verify at time T, Then the submission binds to the rule set with effective start ≤ T < next effective start and the bound version is displayed to admins. When rules change after binding, Then existing in-progress submissions retain their bound version unless an admin triggers Re-evaluate Against Current Rules, which revalidates and updates blocking requirements accordingly. When a future-dated rule set is scheduled, Then admins can run Preview to see diffs against the current set for a selected jurisdiction and program without affecting live submissions.

Admin UI: Jurisdiction/Program Rule Toggles with Environment Isolation and Audit Trail

Given a user has Compliance Admin role in environment E (dev/stage/prod), When they add/edit/toggle a requirement for a jurisdiction and program, Then changes apply only to environment E and do not impact other environments. When saving changes, Then the UI requires a change summary, shows impacted programs/jurisdictions count, and creates a new rule set minor version. Then every change is logged with user, timestamp, environment, before/after diff, and is immutable and queryable by date, user, and entity.

Compliance Checklist Artifact Generation per Payee

Given a submission is locked as Complete, When compliance validation passes, Then the system generates an immutable checklist artifact (PDF and JSON) containing jurisdiction, program, bound rule set version, captured consents, declarations, validation outcomes, and timestamps with restricted values masked. Then the artifact is stored in the vault with a content hash and version number and is available to users with Audit Viewer permission via UI and API. When any compliance-relevant data changes post-lock, Then a new artifact version is created and previous versions remain immutable and retrievable.

Permissions-Tight Vault & Access Controls

"As a security lead, I want sensitive payee data stored and accessed under least-privilege controls so that we reduce breach and audit risk."

Description

Encrypted storage of tax and bank data using field-level encryption and tokenization; strict RBAC aligned with MeritFlow roles, with just-in-time access requests, time-boxed grants, and purpose-of-use logging. Includes per-field access scopes, view watermarking and masking, download restrictions, KMS integration for key management, rotation policies, and comprehensive immutable audit logs of access and changes. Supports export via secure channels (SFTP/API) with redaction options.

Acceptance Criteria

RBAC Enforcement and Just‑In‑Time (JIT) Access Grants

Given a user without the BankData.View scope attempts to open bank account details in the Payee Vault, When the request is made, Then the API returns 403 Forbidden and an audit log entry is created with user, attempted fields, and reason "insufficient_scope". Given a user submits a JIT access request with a purpose-of-use and desired fields, When an approver grants time-boxed access for 30 minutes, Then the user can retrieve only the approved fields during that window and all other fields return 403. Given a JIT grant expires, When the user retries the same endpoint, Then the API returns 403 and the audit log records "expired_grant". Given a user has the TaxData.ViewLast4 scope only, When viewing a W‑9, Then SSN/EIN is displayed as last 4 characters with masking and full value requests return 403. Given a user with PayoutManager role has baseline scopes, When role mapping is updated to remove BankData.View, Then subsequent calls immediately enforce the change without cache lag beyond 60 seconds.

Field‑Level Encryption and Tokenization at Rest

Given direct database access outside the application, When querying columns tagged as sensitive (e.g., account_number, routing_number, TIN), Then only ciphertext or tokens are visible and no plaintext is retrievable. Given a new payee record is created, When sensitive fields are persisted, Then a unique DEK is used per record via envelope encryption with KMS and the audit log records KMS key ID and operation. Given tokenized values are returned to non-privileged services, When those tokens are used to call read endpoints, Then plaintext is never returned unless the caller has the corresponding per-field decrypt scope. Given a backup restore is performed in a staging environment, When records are inspected, Then sensitive fields remain encrypted and cannot be decrypted without access to the production KMS keys. Given key rotation is executed per policy, When rotating KEK in KMS, Then existing data remains decryptable and no read/write operation fails during rotation.

Per‑Field Masking, Watermarking, and Download Restrictions

Given a user with BankData.ViewMasked scope opens a record, When the UI renders bank and tax fields, Then values are masked by default (e.g., ****1234) and an Unmask button is disabled unless BankData.Unmask scope is present. Given a user with BankData.Unmask scope unmaskes a field after selecting a purpose-of-use, When the value is displayed, Then the view includes a visible watermark with user ID, timestamp (UTC), IP, and request ID. Given a user without DownloadSensitive scope attempts to export the record, When clicking download, Then the client shows no option for CSV/PDF export and the server rejects any forged export call with 403 and logs the attempt. Given a permitted export of a PDF view, When the file is generated, Then the watermark appears on each page and unmasked fields reflect only those approved by scope/JIT grant. Given a CSV export is performed, When the redaction profile is applied, Then masked fields are redacted per profile and any attempt to include unapproved columns is omitted and logged.

Immutable Audit Logging of Access and Changes

Given any read of sensitive fields occurs, When the API returns a response, Then an append-only audit entry is written within 5 seconds including actor, role, scopes, fields accessed, purpose-of-use, grant ID (if any), record ID, timestamp (UTC), IP, and outcome. Given a tampering attempt on audit storage, When an integrity check runs, Then hash-chain/signature verification detects modification and raises an alert. Given an Auditor role queries logs, When filtering by user, date range, field, and outcome, Then results are returned within 3 seconds for up to 100k entries and export is available in a signed, read-only format. Given retention policy is 7 years, When older logs are queried, Then they remain readable and verifiably untampered (signature intact) and cannot be deleted by non-admins. Given a failed access attempt, When reviewing logs, Then the specific denial reason (insufficient_scope, expired_grant, purpose_missing) is present.

Secure Export via SFTP/API with Redaction Profiles

Given an integration user with ExportSensitive scope requests an export via SFTP, When the job runs, Then files are delivered over SFTP with server key pinning, and contents adhere to the selected redaction profile. Given an API client calls the exports endpoint, When providing a valid short-lived signed URL request, Then a link valid for <= 15 minutes is returned and expires after first download or TTL, whichever comes first. Given an export includes bank and tax fields, When the "Compliant-Minimum" redaction profile is applied, Then only last4 and masked values are present; full values are excluded. Given an export job completes, When auditing, Then an audit log records exporter, profile, column manifest, record count, checksum (SHA-256), and delivery channel. Given an unauthorized client attempts to fetch an export, When accessing the URL after expiry or without signature, Then a 403/410 is returned and the access attempt is logged.

KMS Integration and Key Rotation Without Downtime

Given configured external KMS keys, When the service requests data encryption/decryption, Then KMS usage is recorded with key IDs and succeeds within p95 < 200 ms per operation. Given a scheduled key rotation event, When rotating KEK, Then application read/write p99 latency does not exceed +20% of baseline and no 5xx errors are introduced. Given a key is disabled in KMS, When the application attempts decryption, Then requests fail closed with 503, data is not exposed, and on-call is paged with key ID context. Given cross-region disaster recovery, When failing over, Then the application uses region-appropriate KMS keys and can decrypt existing data encrypted with multi-region keys. Given KMS access policies are tightened, When a non-vault service without KMS decrypt permission calls decrypt, Then the operation is denied and the attempt is logged.

Purpose‑of‑Use Enforcement Across Workflows

Given a user attempts to unmask a TIN, When no purpose-of-use is supplied, Then the API returns 400 with a machine-readable error and no data is revealed. Given a user supplies a purpose-of-use, When the purpose is not allowed for their role/action, Then the API returns 403 and records the blocked purpose in the audit log. Given a payout batch is being approved, When the approver opens necessary bank fields, Then the purpose-of-use is auto-set to "Payout Approval", displayed to the user, and included in the audit log. Given custom purposes are configured by an admin, When a user selects from the list, Then only active, policy-compliant purposes appear and selections are validated server-side. Given reporting on purposes is requested, When exporting audit data, Then counts of accesses by purpose are accurate and sum to total access events for the period.

Applicant Notifications & Status Tracking

"As an applicant, I want clear prompts and status updates during verification so that I know what to do and when my payout is ready."

Description

Automated, localized notifications and in-portal status indicators for each verification step (tax form needed, bank verification sent, micro-deposits posted, verification success/failure). Templated emails/SMS with merge fields, reminder cadence, and escalation to coordinators on stalls; self-service resubmit/correct flows; activity timeline visible to staff; event webhooks for downstream systems.

Acceptance Criteria

Localized tax form request notification sent upon eligibility check

- Given an applicant begins Payee Verify and the system detects a missing or invalid tax form (W-9 or W-8), When the eligibility check completes, Then the system sends a notification via the applicant's preferred channel(s) within 2 minutes. - And the notification language matches the applicant's locale preference with fallback to English if unavailable. - And the template renders merge fields {applicant_name}, {program_name}, {required_form}, {due_date}, and a secure deep link to the tax form step. - And the send event is recorded in the applicant’s activity timeline with timestamp, channel, template ID, and delivery status. - And no notification is sent if the tax form is already submitted and passes validation within the last 10 minutes.

In-portal status indicators reflect verification step progression

- Given an applicant views the Payee Verify panel, When their step state changes (Tax form needed, Tax form received, Bank verification sent, Micro-deposits posted, Verification success, Verification failure), Then the corresponding status badge updates within 15 seconds. - And each badge shows a label, an icon, and a last-updated timestamp, and meets WCAG AA (contrast ≥ 4.5:1) with accessible aria-labels. - And failure states display actionable guidance and a 'Resubmit' call-to-action. - And statuses shown to staff and applicant are consistent for the same application. - And partial states (e.g., micro-deposits sent but not entered) show an 'Awaiting applicant' substate.

Automated reminders and coordinator escalation on applicant stalls

- Given an applicant has an outstanding action for a verification step, When no activity is recorded for 48 hours, Then a reminder is sent using the step’s template and the applicant's channel preferences. - And up to 3 reminders are sent at 48h, 96h, and 7 days, respecting quiet hours 9pm–8am local time. - And if the step remains incomplete 24 hours after the third reminder, an escalation email and dashboard task are created for the assigned coordinator. - And reminders stop immediately once the step is completed. - And reminders are suppressed while micro-deposit settlement is pending (status 'Deposits in transit').

Self-service resubmission after failed tax or bank verification

- Given a step is in failure state due to validation errors, When the applicant selects 'Resubmit', Then the system reopens the step with field-level error hints and server-side validation on submit. - And prior submissions are retained read-only in the activity timeline with version numbers. - And resubmission limits are enforced at 3 attempts per 24 hours per step. - And upon submit, the status resets to 'Under review' and a confirmation notification is sent and logged. - And duplicate bank accounts are detected and blocked with a clear message guiding the applicant to select an existing verified account or update details.

Staff can view a complete, compliant activity timeline

- Given a staff member opens an application, When viewing the Activity tab, Then all Payee Verify events are listed chronologically with actor (system/applicant/staff), timestamp (ISO 8601), channel, event type, and outcome. - And notification payloads are redacted to exclude full SSN/Tax ID and full account numbers, showing only last 4 digits where applicable. - And the timeline supports filters by event type and date range and can be exported to CSV with the same redaction rules. - And events reflect consistent times across time zones via UTC storage with local-time display. - And failures include error codes and retry outcomes where relevant.

Event webhooks emitted for verification and notification lifecycle

- Given a subscribed webhook endpoint is configured and enabled, When any of the following events occur: status_changed, notification_sent, notification_bounced, bank_verification_initiated, micro_deposits_posted, verification_succeeded, verification_failed, Then a POST is delivered with signed HMAC-SHA256, idempotency key, and event payload within 30 seconds. - And delivery uses at-least-once semantics with exponential backoff retries for up to 24 hours until a 2xx response is received. - And the system provides a replay mechanism by event ID with original signature preserved. - And sensitive fields are redacted consistent with timeline rules. - And webhook delivery attempts and outcomes are visible in the staff timeline.

Coordinators manage localized templates with validated merge fields

- Given a coordinator edits a notification template, When saving, Then merge fields are validated against the allowed set and unknown fields are rejected with suggestions. - And templates support locale variants with fallback chain (e.g., es-MX → es → en) and must specify at least a default locale. - And SMS templates enforce segment limits (160 GSM-7 or 70 UCS-2 per segment) and display estimated segments before save. - And a preview function renders templates with test data, showing both email and SMS previews and character counts. - And templates include required unsubscribe/compliance tokens by channel and prevent save if missing.

Sign-to-Release

Template, route, and e‑sign award agreements with merge fields and clause libraries. Gate disbursements until countersignature is complete, then stamp agreements into the payout ledger—accelerating cycle time while ensuring every release is legally covered and provable.

Requirements

Template Builder with Merge Fields

"As a program manager, I want to create reusable agreement templates that auto-fill with award data so that I can generate accurate agreements in minutes without manual copy-paste."

Description

Provide a reusable agreement template editor with merge fields mapped to MeritFlow applicant, program, and award data. Support draft/publish versioning, required field validation, preview with real award data, and localization. Enforce role-based access to templates by program. Allow WYSIWYG formatting, clause placeholders, and token governance to prevent unapproved free‑text. Ensure templates can be attached to award types and automatically instantiated at award decision time.

Acceptance Criteria

Publishable Template Versioning and Audit

Given a user with Manage Templates permission in Program X and a Draft template v1 exists When the user clicks Publish Then a Published version v1 is created with immutable content and a unique version ID And the editor opens a new Draft v2 for further edits without altering Published v1 And an audit log entry records user, timestamp, version, and change summary And only Published versions are selectable for attachment to award types

Merge Fields Mapping and Token Governance

Given the template editor with an approved merge token catalog for Applicant, Program, and Award When the template is validated or published Then the system rejects any unapproved token and lists them by name and count And Publish is blocked until all unapproved tokens are removed or replaced with approved tokens And the validator confirms all referenced tokens have resolvable mappings to MeritFlow data And if any token marked as required by governance is unmappable for the selected program/award type, Publish is blocked with a specific error And Save as Draft remains allowed even if validation fails, but Publish is not

Preview Agreement with Real Award Data

Given a Published template and the user has view access to Award A in Program X When the user opens Preview and selects Award A Then the preview renders with all merge fields populated from Award A And fields with null data display the configured fallback text And the preview renders within 3 seconds for templates up to 5,000 words

Role-Based Access by Program

Given Program-scoped permissions When a user without Manage Templates permission for Program X attempts to create, edit, or publish a template in Program X Then the action is denied with a 403 error and a UI message explaining insufficient permissions And templates from Program X are not visible or attachable in Program Y to users lacking cross-program rights And users with Manage Templates permission in Program X can only attach templates to award types within Program X

Localization and WYSIWYG Formatting

Given the editor supports multiple locales and WYSIWYG controls When a user switches the template locale to fr-FR Then date, number, and currency merge fields format per fr-FR conventions in preview And locale-specific content is stored per locale and can be independently edited And if a translation for a locale is missing, Publish shows a warning and preview falls back to the default locale for missing strings And pasted content is sanitized to allowed elements (bold, italics, lists, tables, links) with styles normalized to the product stylesheet

Clause Placeholders and Library Integration

Given a versioned clause library When a user inserts a Clause Placeholder and selects clause "Confidentiality v3" Then the placeholder resolves to that clause in preview And on Publish, the template snapshot locks to clause version v3 And if the library updates to v4 later, existing Published templates continue to use v3 until republished And Publish is blocked if any clause placeholder is unresolved

Attach to Award Types and Auto-Instantiation at Decision

Given a Published template is attached to Award Type Y in Program X When an award in Program X of Type Y is marked Approved Then an Agreement Instance is created automatically within 5 seconds using the latest Published template version attached to Type Y And all merge fields populate from the award, applicant, and program data And only one Agreement Instance is created per award per template (idempotent) And if no Published template is attached to Type Y, no instance is created and an admin alert is logged

Clause Library & Conditional Selection

"As legal counsel, I want clauses to be selected automatically based on award conditions so that every agreement includes the correct, approved language without manual review."

Description

Maintain a central, approved clause library with metadata tags (jurisdiction, funding source, risk level, program, language). Provide a rule engine to auto-insert mandatory and optional clauses based on award attributes (amount, country, population served) and applicant answers. Lock non-negotiable clauses, allow optional toggles with audit notes, and support multilingual variants. Track clause versions and render the correct versions in generated agreements.

Acceptance Criteria

Auto-Insert Mandatory Clauses by Award Attributes

Given an award with attributes amount=250000 USD, country=UK, population_served=minors, program=STEM Fellows, funding_source=GovGrant-Alpha, risk_level=High And the clause library contains approved clauses: - C1: Non-negotiable; jurisdiction=UK; risk_level=High - C2: Mandatory when amount>=200000; funding_source=GovGrant-Alpha - C3: Optional; population_served=minors - C4: Mandatory; jurisdiction=US When a user generates an agreement for the award Then the system automatically inserts C1 and C2 and does not insert C4 And presents C3 as optional (pre-selected=false) And records for each inserted/recommended clause the matched rule(s), tag matches, and evaluation timestamp in the selection log And the agreement cannot proceed to preview if any mandatory clause evaluation returns "unresolved" or "false" And the auto-selection completes in ≤2 seconds for up to 100 candidate clauses

Optional Clause Toggle with Audit Trail

Given the generated agreement includes optional clauses O1 and O2 recommended by rules When the Program Manager toggles O1 from off to on Then the system requires a reason code (dropdown) and free-text note (min 10 chars) and captures userId, timestamp, before/after state And the action is written to an immutable audit log and visible in the agreement activity feed And toggling a non-negotiable clause is disabled and, if attempted via API, returns HTTP 403 with error code CLAUSE_LOCKED And the agreement snapshot reflects the change with a new minor revision number

Non-Negotiable Clauses Locked from Editing

Given clause N1 is flagged non-negotiable in the library When any non-Legal Admin user attempts to edit, delete, or deselect N1 in an agreement Then the UI disables edit/remove controls and displays a tooltip "Locked by Legal" And any API attempt to modify N1 returns HTTP 403 with error code CLAUSE_LOCKED And only a Legal Admin can update N1 in the library; existing agreements retain the prior version and show "superseded" status without text mutation And the lock state is enforced consistently across web UI, API, and bulk operations

Multilingual Clause Variant Selection

Given the award’s jurisdiction=Quebec and applicant’s preferred_language=fr-CA And clause M1 has approved variants for en-US and fr-CA And clause M2 has only en-US When generating the agreement with language preference=auto Then the system renders M1 in fr-CA and M2 in en-US with a fallback banner And it logs fallback events with reason=missing_variant and requires Legal Admin approval before release And numberings and cross-references are consistent across language segments And all rendered text passes language-specific typography rules (e.g., non-breaking spaces before punctuation in fr-CA)

Clause Versioning and Rendering in Agreements

Given clause V1 has versions 1.2 (effective_until=2025-06-30) and 1.3 (effective_from=2025-07-01) When an agreement is generated on 2025-08-26 Then version 1.3 is rendered And the agreement stores clause_id=V1 and version=1.3 with content_hash And subsequent edits to the library do not change the stored agreement text And viewing the agreement displays version metadata and a diff link to the previous version

Clause Metadata Tagging and Searchability

Given a Legal Admin is adding new clauses via bulk import CSV When rows are uploaded with missing required tags (jurisdiction, program, language) or invalid values not in the controlled vocabulary Then the import fails for those rows with actionable error messages per row and a downloadable error report And successfully validated rows are created with unique IDs and deduplicated by normalized text+tags fingerprint And the library search can filter by any tag and combine filters (e.g., jurisdiction=UK AND risk_level=High AND language=en-GB) returning results in ≤1 second for up to 10k clauses

Signer Routing & Approval Workflow

"As a grant coordinator, I want to define who signs and in what order so that agreements move smoothly and meet internal approval policies before going to the recipient."

Description

Configure signer roles, sequence (serial/parallel), and conditional routing (e.g., add Department Chair if award > $50k). Include pre-sign internal approvals, delegate rules, deadlines, and fallback routing. Expose a visual workflow builder and per-program routing presets. Validate contact details, handle reassignments, and persist routing history on the award record.

Acceptance Criteria

Serial and Parallel Signer Sequencing

- Given a workflow with Step 1 (parallel: Awardee, Co-PI) and Step 2 (serial: Dept Admin -> Legal -> CFO), When the workflow is initiated, Then sign requests are sent concurrently to Awardee and Co-PI and Step 2 does not start until both complete. - Given a serial step, When any signer in the step completes, Then the next signer is notified within 60 seconds. - Given a parallel step, When one signer completes, Then the others in the same step remain pending and are not skipped. - Given the configured sequence, When the order is changed and republished before initiation, Then new packages follow the updated sequence and in-flight packages retain their original sequence.

Conditional Routing by Award Amount

- Given a rule "If Award Total > 50000 USD add Department Chair after Awardee," When Award Total = 60000, Then the route includes Department Chair in that position. - Given the same rule, When Award Total = 50000, Then Department Chair is not included. - Given the condition value changes before any signatures are collected, When the Award Total is edited to cross the threshold, Then the pending route recalculates and adds/removes Department Chair with an audit entry. - Given multiple rules evaluate true, When routing is generated, Then all applicable nodes are inserted without duplicates and according to configured priorities.

Pre-Sign Internal Approval Gate

- Given internal approvers Finance and Legal are required pre-sign, When any internal approval is pending, Then no external signer notifications are sent and the package shows status "Awaiting Internal Approval." - Given all required internal approvals are Approved, When the last approval is submitted, Then external signing is released and first external notifications are sent within 60 seconds. - Given any internal approver Rejects, When rejection is recorded, Then the workflow moves to Rejected, external steps are canceled, and configured notifications are sent.

Delegation, Reassignment, and History Persistence

- Given a signer has an active delegate, When routing reaches that signer, Then the request is delivered to the delegate and history records delegation with actor, delegate identity, and timestamp. - Given an authorized admin reassigns a signer, When reassignment is confirmed, Then prior access links are revoked, the new signer receives a fresh link, and history captures old/new assignee, actor, reason, and timestamp. - Given role constraints (e.g., must belong to Program's org), When a reassignment violates a constraint, Then the system blocks the change and displays a validation error describing the violated rule. - Given any routing event (sent, delivered, viewed, signed, declined, reassigned, escalated), When it occurs, Then an immutable history entry is written to the award record including event type, actor, UTC timestamp, and relevant metadata.

Deadlines, Reminders, and Fallback Escalation

- Given a signer deadline of 5 calendar days, When 5 days elapse without action, Then the signer is marked Overdue, an escalation notification is sent to the fallback assignee, and routing moves to the fallback path if configured. - Given reminders set to every 2 days with a maximum of 3, When a signer remains pending, Then reminders are sent on schedule and cease after the signer acts or after 3 sends, whichever occurs first. - Given no fallback is configured, When the deadline passes, Then the workflow remains paused, no reassignment occurs, and an alert is sent to the program manager.

Contact Details Validation

- Given a signer or approver email is entered, When it fails RFC 5322 format or violates program domain restrictions, Then saving the workflow is blocked with a specific validation message. - Given an email invitation bounces hard, When the bounce is received from the mail provider, Then the recipient status changes to Undeliverable, routing is paused, and the program manager is notified to update contact details. - Given a required contact field is missing (email or name), When publishing a workflow, Then publishing is blocked until the field is completed.

Visual Workflow Builder and Program Presets

- Given the workflow builder is open, When a user adds roles, steps, deadlines, and conditions, Then the builder validates completeness in real time and prevents publishing while any node is incomplete or invalid. - Given a routing preset named "Grant Default" is saved, When applying it to a program, Then new awards created in that program default to the preset workflow. - Given a preset is updated, When existing awards are mid-route, Then they continue using the original version; only new awards use the updated preset, and the version identifier is stored on each award.

Compliant E‑Signature Capture with Identity Verification

"As an award recipient, I want to sign my agreement online from any device so that I can complete requirements quickly with a legally valid signature."

Description

Provide native e-sign or integrate with trusted providers to capture legally binding signatures compliant with ESIGN, UETA, and eIDAS. Include signer consent, time-stamped certificates, document hashing, and long-term validation. Offer identity verification options (email OTP, SMS OTP, SSO), mobile-friendly signing, accessibility (WCAG 2.1 AA), and timezone-aware timestamps. Support countersignature and multi-signer flows.

Acceptance Criteria

Legal Consent and E-Signature Compliance

Given a signer opens an agreement to sign When they attempt to proceed Then they must explicitly consent to conduct business electronically before accessing signing fields, and the consent text references ESIGN, UETA, and eIDAS Given consent is granted When the signer completes the signature workflow Then the system records intent-to-sign, signer attribution (full name and email), IP address, and user agent in an immutable audit trail Given consent is declined or withdrawn When the signer attempts to continue Then signing is blocked and a consent-withdrawn event is recorded in the audit trail Given the agreement is finalized When the signed PDF is generated Then each signature is represented visually and includes an embedded digital signature certificate indicating the signer identity and signing time

Email OTP Identity Verification

Given Email OTP is configured for identity verification When the signer requests a code Then a single-use 6-digit OTP is sent to the signer's email, the code expires in 5 minutes, and the UI masks the email address Given an OTP has been issued When the signer submits the code Then verification succeeds only if the code matches, is unexpired, and unused; otherwise an error is shown and the attempt is logged Given repeated failures occur When the signer enters 5 incorrect codes within 10 minutes Then the system locks Email OTP verification for 15 minutes and logs the lockout event Given a valid verification When the OTP is accepted Then the signer is allowed to access and sign the agreement and an audit event records the verification method and timestamp

SMS OTP Identity Verification

Given SMS OTP is configured for identity verification with a verified E.164 phone number When the signer requests a code Then a single-use 6-digit OTP is sent via SMS, the code expires in 5 minutes, and no more than 3 codes can be sent within 15 minutes Given an OTP has been issued When the signer submits the code Then verification succeeds only if the code matches, is unexpired, and unused; otherwise an error is shown and the attempt is logged with IP and timestamp Given repeated failures occur When the signer enters 5 incorrect codes within 10 minutes Then the system locks SMS OTP verification for 15 minutes and logs the lockout event Given a valid verification When the OTP is accepted Then the signer is allowed to access and sign the agreement and an audit event records the verification method and timestamp

SSO Identity Verification (SAML/OIDC)

Given SSO is configured with an approved identity provider (SAML 2.0 or OpenID Connect) When the signer selects Sign in with SSO Then only configured IdPs are presented and the authentication flow uses state/nonce to prevent CSRF/replay Given the signer returns from the IdP When the assertion/token is validated Then the signature on the assertion/token is verified, it is not expired, and the email/NameID claim matches the intended signer record; otherwise access is denied and an audit event is recorded Given SSO verification succeeds When the signer returns to the agreement Then the signer can access and sign without additional OTP, and the audit trail records IdP name, subject identifier, and authentication timestamp

Tamper-Evident Audit Trail, Timestamps, Hashing, and LTV

Given an agreement is signed When the completion certificate is generated Then the document's SHA-256 hash is computed and stored in the certificate and audit log, and the certificate includes an RFC 3161 trusted timestamp Given the signed PDF is viewed in a compliant validator When validation is performed offline Then the PDF signature validates using embedded LTV evidence (certificate chain and OCSP/CRL), without contacting external services Given any post-sign modification is attempted When the PDF is altered Then the signature validation fails and the mismatch is detectable via hash comparison Given the audit trail is requested When a program manager exports it Then a non-editable report (PDF and JSON) is produced including event IDs, UTC timestamps with timezone offsets, signer IPs, user agents, and verification methods

Sequential Multi-Signer Countersignature and Disbursement Gate

Given an agreement requires multiple signers with a defined order (applicant -> reviewer -> organization countersigner) When the first signer completes their signature Then the next signer is notified and cannot be skipped unless reassignment rules explicitly allow it and are recorded in the audit trail Given not all required signatures are complete When a user attempts to initiate disbursement via UI or API Then the disbursement action is blocked and the API returns a 409 Conflict with reason Pending countersignature Given the final required signature is applied When the agreement status updates to Fully executed Then the agreement is stamped into the payout ledger with agreement ID, final document hash, signer list, and execution timestamp, and disbursement gating is lifted Given a complex workflow When at least 3 signers are configured with a mix of sequential and parallel groups Then the system routes correctly, collects all required signatures, and produces a single fully executed document and certificate

Accessible, Mobile-Friendly Signing with Timezone-Aware Timestamps

Given a signer uses a mobile device (viewport width >=320px) When they review and sign Then all content reflows without horizontal scrolling, text is legible, and all controls (fields, signature pad, consent checkbox) are operable via touch Given a signer relies on assistive technology When they navigate the signing experience Then all interactive elements are reachable by keyboard, have visible focus, correct programmatic names/roles/states, and meet WCAG 2.1 AA contrast requirements Given timestamps are displayed to the signer When events (viewed, verified, signed) are shown Then times display in the signer's local timezone with explicit UTC offset, while the system stores canonical UTC timestamps in the audit log

Disbursement Gate & Ledger Stamping

"As a finance officer, I want payouts to remain blocked until the agreement is fully executed so that funds are only released when we are legally covered and traceable in the ledger."

Description

Block any payout until all required signatures are captured. Upon countersignature, atomically stamp agreement metadata (agreement ID, hash, template version, clause set, signer identities, timestamps) into the payout ledger and mark the award as release-eligible. Ensure idempotent writes, retry logic, and reconciliation if an agreement is amended. Expose status flags and webhooks for finance and integrations.

Acceptance Criteria

Payout Blocked Until Required Signatures Complete

- Given an award with at least one required signer incomplete, When a payout is initiated via UI, API, or batch, Then the request is rejected with HTTP 409 Conflict and error_code "signatures_pending", and no ledger entries are created or modified, and award.releaseEligible remains false. - Given all required signatures are completed and recorded, When a payout is initiated, Then the gate allows progression to the downstream payout flow and award.releaseEligible is true.

Atomic Ledger Stamp on Final Countersignature

- Given the final countersignature is captured, When the system persists the agreement metadata, Then it writes a single atomic ledger record containing agreementId, agreementHash, templateVersion, clauseSetId, signerIdentities, and signedTimestamps, and in the same transaction sets award.releaseEligible = true, and the operation is all-or-nothing (no partial state on failure). - Given a failure occurs during stamping, When the transaction aborts, Then no ledger record is created and award.releaseEligible remains false, and the system logs the error and schedules a retry.

Idempotent Stamping and Safe Retries

- Given the stamping process is invoked multiple times for the same agreementId and versionHash, When the process runs, Then exactly one ledger record exists keyed by an idempotencyKey derived from (agreementId, versionHash), and subsequent invocations succeed without creating additional records. - Given transient errors occur during stamping, When retry policy is applied, Then the system retries with exponential backoff up to a configurable maxAttempts, and emits a terminal status "stamping_failed" if exhausted. - Given duplicate countersignature events are received, When handlers execute, Then deduplication by idempotencyKey ensures exactly-once observable outcome.

Reconciliation on Agreement Amendment

- Given an agreement is amended after initial signatures, When the amended agreement is finalized with new countersignature, Then the system stamps a new ledger record with updated metadata and marks the previous stamp as superseded with a pointer to the new record. - Given an amendment occurs before disbursement, When the prior release eligibility exists, Then award.releaseEligible is set to false until the amended agreement is countersigned and restamped. - Given an amendment occurs after disbursement, When reconciliation runs, Then the ledger records the amendment with a "post_release_amendment" flag and maintains an immutable audit trail without altering the historical release record.

Status Flags Exposed for Finance and Integrations

- Given any change to agreement/signature/stamping state for an award, When clients query GET /awards/{id}/release-status, Then the response includes canonical flags: signatures_pending, stamping_in_progress, release_eligible, stamp_committed, stamping_failed, amendment_required. - Given a triggering event occurs, When the status is queried within 5 seconds, Then the flags reflect the current state and include updatedAt and a monotonic version for change tracking. - Given the award transitions to release_eligible, When the UI and API are refreshed, Then both present a consistent release_eligible state in the same polling interval.

Webhooks for Downstream Finance Systems

- Given key events (signatures_completed, stamp_committed, release_eligibility_changed, stamping_failed, agreement_amended), When they occur, Then a webhook is sent to each registered endpoint with HMAC-signed headers, an idempotency key, and a payload containing agreement metadata (agreementId, agreementHash, templateVersion, clauseSetId, signer identities, timestamps, and awardId). - Given a webhook delivery fails with non-2xx or timeout, When retry policy executes, Then deliveries are retried with exponential backoff for up to a configurable window (e.g., 24 hours) and failures are surfaced in an admin console for replay. - Given duplicate webhook deliveries, When receivers process the event, Then deduplication via the idempotency key ensures idempotent downstream handling; the system guarantees at-least-once delivery.

Evidence Package & Audit Trail

"As a compliance manager, I want a complete evidence package for each executed agreement so that I can prove enforceability and pass audits without manual collation."

Description

Generate a tamper-evident activity log and certificate of completion including IPs, user agents, signer events, approvals, and timestamps. Store a cryptographic hash of the final PDF and retain the evidence package with the award record. Support exports, retention policies, and legal hold. Provide API/webhooks for downstream compliance systems.

Acceptance Criteria

Tamper‑Evident Audit Log Generation on Countersignature

Given an award agreement reaches countersignature When the system finalizes the agreement Then it generates an immutable audit log for that agreement containing: event_type, event_timestamp (UTC ISO 8601 with millisecond precision), actor_user_id or service_id, actor_role, actor_email (if human), actor_ip, actor_user_agent, agreement_version_id, action_result, and event_sequence And each audit event is hashed with SHA-256 and chained via previous_event_hash to produce a package_tip_hash And the package is signed with the platform certificate and is machine-verifiable And the integrity verification endpoint returns verified=true immediately after generation And if any stored audit event is altered post-generation, the verification endpoint returns verified=false and records an integrity_failure audit event

Certificate of Completion Content and Attachment

Given the agreement is completed When the certificate of completion is generated Then the PDF includes: program_name, award_id, agreement_id, signer_full_names, signer_emails, signer_roles, per-signer signing_timestamp (UTC), per-signer IP and user_agent, final_document_sha256, page_count, and audit_log_tip_hash And the certificate includes a verification URL and QR code referencing the evidence package ID And the certificate PDF is attached to the award record and is downloadable by users with Award:View permission

Cryptographic Hash Storage and Verification API

Given a final signed PDF is stored When the system persists the document Then it computes SHA-256 and stores the hash immutably with the award record And when a client calls GET /api/evidence/{id}/verify Then the system recomputes the hash and returns 200 with match=true and the stored hash And if the stored file is corrupted or replaced Then the endpoint returns match=false, emits an alert, and records an evidence_integrity_mismatch audit event

Retention Policy and Legal Hold Enforcement

Given a program-level retention period (in years) is configured When an evidence package is created Then deletion_scheduled_at is set to created_at + retention_period And when legal hold is applied to an award Then deletion is blocked and deletion_scheduled_at is cleared until the hold is removed And when the retention date is reached with no legal hold Then the evidence package and associated files are deleted and a deletion audit event with actor=system is recorded And when deletion is attempted during legal hold Then the system returns HTTP 423 Locked and records a denied_deletion audit event

Export Evidence Package and Audit Trail

Given an admin selects one or more awards for export When requesting an Evidence Export Then the system produces a ZIP containing: final_agreement.pdf, certificate.pdf, audit_log.json, and manifest.txt with SHA-256 checksums for each file And exports for up to 100 awards complete within 2 minutes, and larger sets begin streaming within 30 seconds And when exporting via API Then filters by date range, program_id, and status are supported and validated And the ZIP is signed with a platform signature and includes verification instructions

Compliance Webhooks Delivery and Security

Given a subscribed webhook endpoint exists When events agreement.completed, evidence.created, evidence.verified, retention.deleted, legal_hold.applied, or legal_hold.removed occur Then the system sends a POST with JSON payload including event_id, event_type, occurred_at (UTC), award_id, agreement_id, evidence_id (when applicable), and a signature And each request includes an X-Signature header containing an HMAC-SHA256 over the body using the shared secret And when the endpoint returns 2xx Then delivery is marked succeeded; otherwise the system retries up to 10 times with exponential backoff and jitter over 24 hours And duplicate deliveries include the same idempotency key header to enable deduplication

Acceptance Criteria

Readability Coach

Per‑field and page‑level readability scoring with target grade‑level goals. Generates tone‑matched rewrites (plain language, bilingual variants) that keep legal essentials intact while removing complexity. Side‑by‑side previews and bulk apply let teams standardize clarity in minutes, improving comprehension for diverse applicants and boosting completion rates.

Requirements

Real-time Readability Scoring

"As a grants coordinator, I want exports that match each sponsor’s format and accessibility requirements so that submissions are accepted without rework."

Description

Offers a template engine to assemble sponsor-branded reports with accessible layouts (PDF/UA), DOCX exports, and a machine-readable JSON evidence bundle (findings, metrics, diffs, screenshots, hashes). Supports configurable sections (executive summary, methodology, findings, improvements, approvals) and localization. Ensures generated documents meet WCAG/Section 508 requirements, embed version metadata, and include cryptographic hashes for integrity. Enables delivery via download, email, SFTP, or API to sponsor systems.

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Budget-Guarding Blake

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Sponsor-Savvy Samira

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Integrations-Minded Imani

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Accessibility-First Alex

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Pipeline-Boosting Priya

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Decision-Ready Devon

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

Context Shield

Requirements

Indirect Identifier Detection Engine

Description

Acceptance Criteria

Multi-Modal Ingestion & OCR

Description

Acceptance Criteria

Layout-Preserving Redaction

Description

Acceptance Criteria

Configurable Policies & Exceptions

Description

Acceptance Criteria

Reviewer-Safe Workflow Integration

Description

Acceptance Criteria

Redaction QA & Feedback Loop

Description

Acceptance Criteria

Audit Trail & Access Controls

Description

Acceptance Criteria

MetaScrub

Requirements

Universal Metadata Scrubbing Engine

Description

Acceptance Criteria

Policy-Based Scrub Rules per Program

Description

Acceptance Criteria