docs/snap-negative-vertical-slice-minimal-spec.md
Linked repository file from this build.
# SNAP Negative review specification
Status: current behavior authority. Reconciled September 13, 2026.
Iris is a synthetic SNAP Negative review application. The [field inventory](./FS-Neg-fields-and-values.md)
controls FNS-245 field meanings and codes. The template contains FS Neg and FS Computation.
FS Workbook belongs to SNAP Positive. PA CAP is not a Negative question or calculation gate.
Historic PA CAP values have no effect.
The application uses synthetic reviews and PDFs. It does not send email, write the external
EPP database, call a federal API, or upload to QCS. Staff upload a transmittal file through
the QCS web portal. The current downloadable TSV is a field export, not a certified federal
wire format. Test transmittal generation, notice PDFs, print/mail queues and actual memo
sending remain outside this iteration.
A case is the eCIS file (`caseNumber`). A review is the QC investigation (`reviewNumber`).
Routes and storage use FFY plus review number within this single-program sample environment.
Prefixes 60/61 have five digits, and 65/66 have six. Numbers can repeat across FFYs.
Generated closed/suspended numbers run from 60001 through 61999, and rejected numbers run
from 650001 through 669999. The fixed 60001 reset fixture belongs only to FFY 2026.
## Terms and approval flags
Examiner screens use Valid, Invalid and Drop. Stored `clean` and `error` values remain
compatible with historic records. The report is Program Error Summary, shortened to
Error summary on compact screens. ERC means the old Error Reporting Call and belongs in
the glossary only.
Approval belongs to each stakeholder. The following flags retain actor and time:
| Flag | Effect |
| ---------------------- | ------------------------------------------------------------------------------------ |
| Supervisor-approved | Completes supervisor verification. A covering manager can set it. |
| PEC-approved | Generates the draft memo and opens manager perusal. |
| Memo-approved | Records the outbound letter and fixes its assignment. It does not release reporting. |
| Error-summary released | Includes a non-drop review in Program Error Summary and the transmittal file. |
| Drop-approved | Manager approval includes a Drop in the transmittal file only. |
Old Approved states do not imply release. Migration invalidates old eligibility projections.
Saved snapshots remain intact. Report and export queries read the release flags, including
when a projection has not yet been rebuilt.
## Workflow and roles
| State | Actor and action |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| Active / Needs changes | Assigned examiner edits facts and submits. |
| Awaiting supervisor | Supervisor or covering program manager verifies or requests changes. |
| Awaiting PEC | PEC denies, gives conditions, or upholds. PEC cannot edit facts. |
| Awaiting manager | Program manager checks the review and memo, requests examiner changes, or approves a Drop. |
| Awaiting CAO response | Program manager records response, root cause and deadline. |
| Released to reporting | Reporting and transmittal inclusion after manager release. |
| Dropped | Manager-approved Drop, transmittal only. |
The Review-tab defect map is not confirmed. Non-drop supervisor approval/routing and
memo type classification show an explicit pending-map message and cannot proceed.
Do not replace this guard with a test for `value != 1`, a guessed list, or a manual type
picker. Ordinary answers differ by field. The [knowledge register](./knowledge-register.md)
retains the unresolved decisions. Existing PEC queue records can retain decisions and
received snapshots. A memo with an unresolved type cannot be approved.
Only the examiner edits federal review facts, including outcome and error assignment.
Supervisors and managers return the review to the examiner for corrections. A manager
can cover supervisor verification but must still perform the manager step after PEC.
Examiners cannot cover supervisors. Supervisors cannot release reporting. Admin and
statistics import samples and rebind algorithms. Program manager, statistics and admin
publish dated policy numbers. Publishing policy does not grant algorithm rebind permission.
Drops retain one examiner-selected kind: Refusal to comply, Failure to comply, or Not
subject to review. They pass supervisor and manager verification and skip PEC and memos.
There is no FNS drop or likely-conclusion ruleset. The app does not inspect narrative
content or require ordinary computation for a Drop. Disposition 2 and NSTR reason remain
ordinary examiner-entered fields. No guessed extra fields apply to a drop kind.
Submission runs the bound edit check. Non-drop submission requires current Final Results
and required coded fields. Senior decisions recheck facts before approval or a finding
refusal. Refusal retains reason, actor and time. Changed facts invalidate prior checks.
The Activity log remains. PEC conditions and working notes remain separate from facts.
## Memo and CAO response
The review has a Memo tab. PEC approval automatically creates a letter from the review
identity, first variance pair and narrative. Program manager may edit it after PEC and
before memo approval. There is no separate memo-author workflow step.
The five type labels are Error under threshold, Info memo, Timeliness info memo, Positive
or negative error finding, and Timeliness finding. The Review-tab map must be confirmed
before automatic classification can choose between processing and timeliness causes.
Valid cases can have info memos. Drops cannot have memos.
Memo approval records outbound status only and locks the letter. The second tab area,
Error summary reporting, records CAO agreement with the CAO-reported root cause, dispute,
or no response. The deadline is visible and editable. A dated policy may supply default
response days. The initial table leaves that unprovided value unset.
Release requires an agreement with a nonblank root cause, or recorded no response after
the deadline, followed by an explicit manager release. Dispute blocks release. A dispute
cannot be recast as no response to bypass the unresolved reassignment path. Manager
kickback returns Needs changes to the examiner before memo approval. No CAO messages
are sent by the application.
## Rules, policy and computation
Reviews bind immutable calculation/check IDs. Old missing IDs resolve to fixed legacy
versions. Deploying code does not rewrite saved rules. Apply new rules is available to
admin/statistics on an active or returned review and invalidates Final Results and checks.
Calculation v4 adds dated policy and self-employment losses. Calculations v1-v3 retain
their prior formulas and supported windows. Check v3 remains the bound field check.
Published policy rows are immutable and dated by `effectiveFrom`. Import stamps `policyId`
and the selected table. A later publication cannot rewrite that review. Older stored
reviews bind to the original FFY 2026 table. The initial table starts October 2025 and
remains in force for v4 until a later effective table is published. No FY27 income or
allotment values are invented. A new FY27 draft starts with a $59 error threshold, while
the initial FFY 2026 table uses $58.
The Policy page uses the shared navigation and toolbar and loads its tables with the route.
It has all 20 household rows for gross/net limits, standard deductions and
allotments. It also has heating/non-heating/limited/telephone/no SUA, shelter cap and
income percentage, homeless deduction, minimum benefit, earned-income percentage,
farm/non-farm expense allowances, error threshold and memo response days. It does not
contain calculation steps or edit-check code. Formula changes still require a developer
change and new algorithm version.
The ordinary grid is Eligibility, Comp I, Comp II and Final SAQC. Income uses a dialog
for Add or edit. Confirm adds one compact row with member, type/category and a larger
amount. The dialog keeps the grid in place, supports Escape/Cancel, and returns focus to
the row or Add income button. Self-employment can show net or gross/expenses and accepts losses. Farm net gain
and loss, non-farm net, and combined profit/loss follow the transcribed AF block. Positive
combined net feeds line 1. Negative combined net feeds line 8 and is subtracted on line 9.
Zero feeds neither. The workbook's Eligibility line-9 sign anomaly is documented in the
knowledge register. The implementation follows the requested subtraction consistently.
Each input column has explicit Save and draft Reset. Drafts do not enter general autosave.
Final Results requires saved columns and chooses the sole populated examiner column, or
the smallest absolute benefit error, with Comp I winning ties. The stored input/result
snapshot remains visible. Final SAQC names Comp I or Comp II and shows its selection reason.
The error row compares Final SAQC with Eligibility only. It shows absolute dollars plus
Overissuance or Underissuance. Under-threshold Invalid amounts are green, reportable
amounts are red, and Valid with no reportable amount has no error color. Per-column
numeric differences are a user preference, off by default. Color is accompanied by text.
Error magnitude split opens at most six additional full computation columns, one changed
input or income discrepancy each. It ranks absolute benefit error largest first. It adds
no tab or extra result lines. Invalid hypothetical combinations do not suppress other
valid discrepancy columns.
Education net remains `max(grant - expenses, 0)`. Proration uses the workbook's 30-day
formula, floors to dollars, returns zero for monthly benefit at or below $10 or day 31,
and leaves a blank application day unprorated. Household sizes are 1-20 under v2-v4 and
1-8 under v1. Net income equal to the limit is a retained demo assumption.
## Examiner sheet, persistence and notes
Sections follow the forms: Case management (I), Identifying information (II), Analysis of
review activity (III), Description of variances (IV), Reserved coding (Items 19-20), State
use, and Explanation of findings (V). General identity is part of II. Household and
Computation each have one section. FS 75 explains ESAP membership and does not enforce ESAP.
Each section has Clear and Reset. Clear all and Reset all require confirmation. Reset
uses the received copy: import for examiner, submission for supervisor, supervisor/PEC
copy for manager. Fact controls remain locked for other roles. A missing historic received
copy disables Reset rather than inventing one. PEC never resets facts.
The Review UI edits one element/nature pair, while storage retains an array. New commands
cannot add a second pair. Historic extra pairs remain readable. Memo, reporting and
transmittal output use the first pair. Narrative preset names remain, without invented
insert-on-select bodies.
Clerk unsafe metadata stores `autosave` and `showComputationDiffs`, both default off.
Autosave on enables the one-minute idle timer. Save, navigation and page hide still flush
normal fields. Computation columns use explicit Save. A short client undo stack supports
Ctrl+Z, keeps history across Save and tab changes, and restores the pre-Clear/Reset state.
Leaving the review page may discard undo. It is not server history or event sourcing.
Working notes, field linking and the separate PEC conditions editor await management guidance.
The workspace has no Notes side panel. Existing note data remains stored. Return reasons
and PEC decision text remain readable in Activity, with line breaks preserved.
The review narrative has one editor on Review. Documents retain the dedicated PDF tab,
required names and purpose text, scoped download and guarded attachment. A PDF is at most
10 MiB. Income has at most 100 rows per scenario. Money inputs use integer cents up to
$1,000,000. Dates and month controls emit validated ISO formats.
Appointments retain Eastern wall-clock date/time. Notice selection and generation remain
pending. The planned notice rule uses the CAO-issued benefit amount: below $100 permits
telephone and face-to-face, and at least $100 permits face-to-face only. The current UI
does not edit that amount or offer notice templates.
## Intake, search and queues
The parser follows sibling VBA commit `82d3de5`: BIS Delim SNAP, Files of Record HBG/PGH/SE,
and Log of Records. Negative intake combines the closed/suspended and rejected A:AP pipe
rows with quoted text support. No individual file or workbook join is required. Source
lineage remains exact. The synthetic attestation is still required. The knowledge register
contains the verified column map. Import starts unfinished examiner work and stamps its
received snapshot. Refresh preserves algorithm/policy bindings and cannot refresh a Drop.
Header search has filter and search buttons at the right, in that order. Each responds to
hover and focus. Search submits the current information. Filter opens the quick fields and
an Advanced search action. Advanced controls keep sample month, number and name visible.
Month filters use native month inputs. Operators combine comparison and exclusion with
short labels, and display one input or two bounds as needed.
Search Reviews, Clear Filters and Clear Sort remain at the lower right. Add Sort sits next
to Add Filter. Ordered sorts can use fields outside the displayed columns. Column headings
toggle ascending/descending order. Relevance is the default and Clear Sort restores it.
URL state retains filters, selected columns, ordered sorts and page. Queries remain scoped
and paginated on the server and select only requested display fields. No typo correction
is claimed. Mail desk keeps sequential multi-PDF attachment with partial-failure retry.
Reviews and Approval Queue retain their common folder layout, flags, version-based unread
state, and 10-row default SQL pages, with 5/10/25/50 choices. Reviews, Approval Queue, Home
and sidebar refresh every five minutes while visible. Manager queues include supervisor
coverage and the separate manager/CAO work. Opening an older version cannot mark a newer
save read.
The notification flyout shows time, review number only and event kind in compact rows.
Ten fit before internal scrolling. Looking does not clear. Clear notifications marks the
scoped recipient's current notifications read. Opening a row can mark it read and navigate.
Polling remains five minutes with stale-focus refresh and preference-triggered refresh.
## Identity, reports and deployment
Clerk server metadata establishes role, staff ID and program. Missing/invalid public
metadata after sign-in shows a blocking account-setup message naming the fields and the
QC administrator who assigns Clerk metadata. It does not silently bounce to landing.
Unsafe metadata grants no permissions. The 14-account demo roster, scoped test identity,
and development View as retain their existing limits.
Reports remains available to program manager, statistics and admin. Program Error Summary
uses released non-drop reviews. Progress charts can show all scoped work. Month, examiner
and county filters apply to charts and CSV runs. The first recorded element/nature pair
supplies the error breakdown. Root cause is CAO-reported, never inferred at PEC. The ten
most recent internal CSV runs last only for the page session.
The Exports page selects sample months and rebuilds downloads from saved scoped reviews.
Statistics can download the transmittal field TSV from released reviews plus manager-approved
Drops. The legacy EPP adapter remains downloadable for its existing senior roles but does
not write the external tracker. All exports quote controls and protect spreadsheet cells.
Storage keeps append-only transactional snapshots, a small query index and inbox events,
with server command replay, retry IDs and stale-write detection. See [data loading](./data-loading.md)
for migration/backfill operations and [implementation status](./implementation-status.md)
for validation. Passing synthetic tests does not establish workbook execution parity,
policy approval, federal format acceptance, records management or production readiness.
September 21 intake layout verification: all 42 user-confirmed headers and their
uses are recorded in [BIS Negative input fields](./bis-negative-input.md). The parser
accepts an optional exact-order header row and includes address line 2, middle
initial and telephone. Other source fields remain in exact raw lineage pending
confirmed destinations/code meanings. Synthetic attestation remains required.