Functional Requirements

The atomic, testable, MoSCoW-tagged functional requirements catalogue for the Sindh IT Portal — Facilitation Desk (SITP), organized by module, with bidirectional traceability to the User Stories in /specs/en/01-prd/ and the Test Cases in 13-test-strategy/.

1. How to Read This Document

This document is the functional contract between the PRD (what users want) and the engineering/test effort (what the system must do and how we verify it). Each requirement is written to be atomic, unambiguous, and independently testable.

1.1 Reading order for a single requirement

Module (H2) → Requirement (FR-<MOD>-<nnn>) → Acceptance criteria → Traces to User Story (US-...) → verified by Test Case (TC-<EPIC>-<nnn>-<nn>).

1.2 MoSCoW tags

Every FR carries exactly one MoSCoW priority (per _conventions.md §5):

• [M] Must — V1 launch blocker.
• [S] Should — V1, soon after launch (first stabilization release).
• [C] Could — Nice-to-have in V1 if capacity allows.
• [W] Won't — Explicitly deferred to a later phase.

All FRs in this document are V1 scope; the tag controls sequencing, not inclusion. The tag aligns with the roadmap in /specs/en/14-roadmap-release/.

1.3 Traceability

• Forward — each FR ends with a Traces to line listing the User Story ID(s) in /specs/en/01-prd/ it realizes.
• Backward — the PRD's User Stories reference FR IDs inline via Satisfies FR-....
• Downstream — Test Cases (TC-<EPIC>-<nnn>-<nn>) are derived from the Acceptance criteria bullets and live in /specs/en/13-test-strategy/.
• IDs are stable, language-neutral, and never translated.

1.4 Module code map

2. Requirement Template

Every requirement in this document follows this exact structure:

#### FR-<MOD>-<nnn> — <short title in imperative mood>  [M|S|C|W]

**Description.** <one or two sentences, imperative, stating what the system must do.
Behavior-only; no UI implementation detail.>

**Rationale.** <why this requirement exists — the decision, risk, or user need
it serves. Reference _context.md sections where applicable.>

**Acceptance criteria.**
- <testable, observable, single-condition bullet>
- <testable, observable, single-condition bullet>
- <each bullet maps to one or more Gherkin Scenario in the traced US>

**Traces to.** US-<EPIC>-nnn (, US-<EPIC>-nnn ...)

Authoring rules:

• One behavior per FR. If acceptance criteria imply two distinct behaviors, split the FR.
• No "and/or" hiding two requirements. No vague qualifiers ("fast", "user-friendly").
• Each acceptance bullet must be verifiable by at least one test case.
• Where the PRD already specifies a Gherkin Scenario, the acceptance bullets here mirror its conditions in imperative form (not Gherkin syntax).

3. Requirements by Module

PUB — Public Site

Epic E1. The unauthenticated, multilingual front door: information pages, FAQ/help center, AI chatbot, SEO/hreflang, service catalog, public transparency snapshot, onboarding wizard. Traces to US-PUB-001 … US-PUB-006.

FR-PUB-001 — Render every public page in EN, UR, and SD [M]

Description. The system must render all public-facing pages (home, about, services, FAQ, help, contact, transparency dashboard) in English, Urdu, and Sindhi, with the active language selectable by the visitor and persisted per session/browser.

Rationale. Trilingual access is a locked decision (_context.md §2). EN is the master source; UR and SD are parallel translations.

Acceptance criteria.

• Each public page exists in three locale variants with no fallback strings visible to the visitor.
• A language switcher is present on every public page and updates all visible text on selection.
• The selected language is reflected in the URL (locale prefix or locale-aware routing).
• A visitor who returns later sees their last-selected language preserved.
• Terms render using the approved translations in _glossary.md.

Traces to. US-PUB-001

FR-PUB-002 — Render Urdu and Sindhi with right-to-left layout [M]

Description. The system must render the Urdu and Sindhi locales in right-to-left (RTL) layout without inline direction hacks, and use the locked typefaces (Noto Nastaliq Urdu for UR, Noto Naskh Arabic for SD).

Rationale. RTL is required for UR/SD per _context.md §2; renderer-driven direction is the convention in _conventions.md §2.

Acceptance criteria.

• Selecting UR or SD flips the entire page layout to RTL, including navigation, tables, forms, and charts.
• Selecting EN restores left-to-right layout.
• Typography for UR uses Noto Nastaliq Urdu and for SD uses Noto Naskh Arabic.
• No truncated or mis-aligned elements are present in RTL rendering of any public page.

Traces to. US-PUB-001

FR-PUB-003 — Provide a searchable, curated FAQ and help center [M]

Description. The system must provide a public FAQ/help center whose articles are searchable by keyword in the visitor's active language, with results ranked by relevance and an escalation path when no results are found.

Rationale. Self-service reduces avoidable tickets (deflection, see KB module) and supports visitors before sign-up.

Acceptance criteria.

• A keyword search returns articles in the active language ranked by relevance.
• Each result links to the full article.
• A zero-result state offers a link to the AI chatbot and a "contact us" option.
• Search indexes UR and SD content correctly (not transliterated to EN).
• Articles are sourced from the Knowledge Base (see KB module) so they stay synchronized.

Traces to. US-PUB-002, US-KB-001

FR-PUB-004 — Offer an AI chatbot for guidance and guided ticket filing [M]

Description. The system must offer a public AI chatbot that answers from approved knowledge sources in the visitor's language, can pre-populate a ticket draft, and can hand off to a live facilitator with the transcript attached.

Rationale. Locked decision (chatbot is one of the 11 AI capabilities, _context.md §4); must integrate with intake and deflection.

Acceptance criteria.

• The chatbot responds in the visitor's active language and cites the source article/FAQ where applicable.
• When the visitor confirms intent to file, the chatbot produces a ticket draft (category, title, description) and routes the visitor to the filing flow for review and submission.
• When the chatbot cannot answer with sufficient confidence, it offers hand-off to a live facilitator; on acceptance, a chat or ticket session is created and routed to the next available facilitator with the transcript attached.
• The chatbot is gated behind a feature flag (FR-FFG-001) and degrades gracefully when disabled.

Traces to. US-PUB-003, US-AI-006

FR-PUB-005 — Emit hreflang alternates, sitemap, and structured data for SEO [S]

Description. Every public page must declare language alternates via hreflang link tags, expose a per-locale sitemap entry, and include structured-data markup for catalogued services and FAQ articles.

Rationale. Multilingual SEO is locked as Should (US-PUB-004); ensures correct-language URLs reach users and crawlers.

Acceptance criteria.

• Each public page's HTML head contains hreflang link tags for EN, UR, SD plus an x-default.
• A sitemap.xml entry exists for each language version of each public page.
• Service-catalog and FAQ pages emit structured-data markup that validates against the chosen schema.
• The locale-aware URLs are crawlable and stable.

Traces to. US-PUB-004

FR-PUB-006 — Provide an entity-aware onboarding wizard [S]

Description. The system must provide an onboarding wizard that asks the visitor's entity type (one of the five locked types) and presents tailored registration requirements, a document checklist, and a direct link to start registration.

Rationale. Reduces friction for first-time registrants; locks in the five entity-type decision (_context.md §5).

Acceptance criteria.

• The wizard offers the five entity types: SECP company, sole proprietor/partnership, freelancer/individual, foreign branch, early startup (provisional).
• Selecting a type surfaces the registration fields and documents specific to that type.
• The wizard offers a downloadable/ printable checklist and a direct link to start registration.
• An anonymous visitor's progress is preserved and attached to a new account when they register.
• The wizard is resumable from the point the visitor left off.

Traces to. US-PUB-005, US-ORG-001

FR-PUB-007 — Publish a filterable service catalog [M]

Description. The system must publish a service catalog of departments and service categories the Portal accepts, filterable by department and category, with each entry linking to its SOPs, downloadable forms, and SLA expectations.

Rationale. Visitors need to know what they can raise and the expectations up front (transparency).

Acceptance criteria.

• The catalog lists every department and category the Portal handles.
• Each entry links to the relevant SOP(s), downloadable forms, and stated SLA.
• The catalog is filterable by department and by category.
• Forms are downloadable without authentication.
• The catalog renders in EN, UR, SD (RTL for UR/SD).

Traces to. US-PUB-006, US-KB-001

FR-PUB-008 — Render a public transparency dashboard (aggregate, PII-free) [M]

Description. The system must render a public, no-login dashboard showing aggregate Portal metrics (total tickets filed, percent resolved within SLA, average resolution time, volume by department), with no PII or ticket-level detail exposed.

Rationale. Locked decision (public transparency dashboard, _context.md §4 module I); ensures accountability without breaching privacy.

Acceptance criteria.

• The dashboard is accessible without authentication.
• Displayed metrics include at minimum: total tickets filed, % resolved within SLA, average resolution time, volume by department.
• No company name, individual name, ticket ID, or free-text content is exposed.
• Small-cell suppression is applied so any group smaller than the configured minimum size is hidden.
• Figures match the source data within the dashboard's published refresh window.
• The dashboard renders in EN, UR, SD and meets WCAG 2.1 AA.

Traces to. US-PUB-006, US-ANL-005

FR-PUB-009 — Meet WCAG 2.1 AA across all three languages [M]

Description. All public pages must meet WCAG 2.1 AA in EN, UR, and SD, including RTL rendering, keyboard navigation, screen-reader semantics, and sufficient color contrast.

Rationale. Locked decision (_context.md §2); mandatory for government services.

Acceptance criteria.

• Automated and manual WCAG 2.1 AA audits pass on every public page in all three locales.
• All interactive elements are keyboard accessible with visible focus states.
• Color-contrast ratios meet AA thresholds across the locked Ajrak palette.
• Screen readers announce page structure, language, and dynamic updates correctly.
• Forms expose labels, error messages, and instructions programmatically.

Traces to. US-PUB-001, US-PUB-006

TKT — Ticketing Core

Epic E2. The full ticket lifecycle: dynamic conditional forms, AI routing, tracking ID, anonymous status lookup, drafts, sub-tasks, merge/split, link/watchers/CC, bulk actions, proof-of-resolution gate, auto-close, reopen, appeal, CSAT, SLA with pause/resume, escalation ladder, confidential/VIP access control. Traces to US-TKT-001 … US-TKT-006. Workflow detail in /specs/en/06-ticket-workflow/.

FR-TKT-001 — Generate meaningful tracking IDs [M]

Description. The system must generate a tracking ID in the format SITP-YYYY-<DEPT>-<NNNNNN> for every ticket, where YYYY is the year, <DEPT> is the routed department's code, and <NNNNNN> is a zero-padded sequence.

Rationale. Locked ID format (_context.md §7); meaningful IDs aid routing, search, and auditability.

Acceptance criteria.

• Every created ticket receives an ID matching the regex ^SITP-\d{4}-[A-Z]{3,5}-\d{6}$.
• IDs are unique across the lifetime of the system.
• The <DEPT> segment reflects the department routed at creation; re-routing updates routing state but not the original ID.
• The ID is shown to the filer immediately and included in all confirmations and notifications.

Traces to. US-TKT-001

FR-TKT-002 — Render a dynamic, conditional intake form per department and category [M]

Description. The system must render a ticket intake form whose fields adapt to the selected department and category, surfacing only the fields that category requires and making them mandatory.

Rationale. Each department/category needs different evidence; avoids asking for irrelevant fields (US-TKT-001).

Acceptance criteria.

• Selecting department and category re-renders the form with the category-specific field set.
• Fields required by the category are mandatory; non-relevant fields are hidden.
• Submission is blocked until all required fields are valid.
• The field schema is configurable per department/category without code changes.
• Common fields (title, description, department, category) are always present.

Traces to. US-TKT-001

FR-TKT-003 — Save a ticket as a draft and resume later [M]

Description. The system must let a Company Representative save a partially completed ticket as a draft, list it under their drafts, and resume it later (including from another device) with all fields and attachments restored.

Rationale. Filers may need to gather evidence; lock-in of "draft & save-later" decision (_context.md §4 module B).

Acceptance criteria.

• A "Save as draft" action persists form state and any staged attachments.
• Drafts are listed under the representative's drafts view.
• Resuming restores all fields and attachments, including from a different authenticated session.
• Drafts have a configurable retention horizon; the representative is warned before expiry.
• Submitting a draft consumes it; deleting discards it permanently.

Traces to. US-TKT-004

FR-TKT-004 — Validate attachment size and type at intake [M]

Description. The system must validate every ticket attachment against the configured per-file and per-submission size and type limits at the point of submission, rejecting out-of-policy files with a specific message.

Rationale. Aligns with file-handling policy (FILE module) and prevents bad inputs.

Acceptance criteria.

• Per-file size and per-submission total size limits are enforced.
• Allowed MIME types are enforced (e.g., PDF, common image types, Office formats); executables and unknown types are rejected.
• On rejection, the message states the specific limit violated.
• Validation runs both client-side (UX) and server-side (authoritative).

Traces to. US-TKT-001, US-FILE-001

FR-TKT-005 — Produce an AI routing suggestion at intake [M]

Description. For every new ticket, the system must produce an AI-suggested department, section, and urgency level with a confidence score, attached to the ticket for triage officer review.

Rationale. Locked AI capability (auto-routing/classification, _context.md §4 module E).

Acceptance criteria.

• A suggestion (department, section, urgency, confidence) is attached to every new ticket asynchronously after submission.
• The triage officer can accept, modify, or reject the suggestion.
• Officer override is audit-logged with the original suggestion, the override, and the actor identity.
• When AI is unavailable or below confidence threshold, the ticket enters the manual triage queue without blocking.

Traces to. US-TKT-002, US-AI-002

FR-TKT-006 — Allow anonymous status lookup by tracking ID [M]

Description. The system must let any person look up a ticket's status by its tracking ID without authentication, exposing only public status information.

Rationale. Locked behaviour (status tracking by ID, no login — modelled on CPGRAMS, _context.md §1).

Acceptance criteria.

• A public tracking page accepts a tracking ID and returns current status, handling department, last public status-change date, and SLA clock state.
• No internal notes, attachments, or staff identifiers are exposed.
• An invalid or unknown ID returns a generic "not found" with no information leakage about existence.
• Repeated invalid attempts are rate-limited and CAPTCHA-gated after a threshold.

Traces to. US-TKT-003

FR-TKT-007 — Track SLA with pause, resume, and holiday awareness [M]

Description. The system must track each ticket against its SLA tier (default 2/5/10 days, configurable), pausing the SLA clock on await (company response), weekends, and Sindh public holidays.

Rationale. Locked SLA behaviour (_context.md §5); fairness requires excluding time outside the dept's control.

Acceptance criteria.

• Each ticket carries an SLA tier with due timestamps computed from the tier's days.
• Awaiting-company-response status pauses the SLA clock; company response resumes it.
• Weekends and entries in the Sindh public-holiday calendar are excluded from SLA elapsed time.
• The SLA clock state (running/paused/breached) is visible to staff and (in summary) to the filer.
• Tier assignment is configurable per department/category/urgency.

Traces to. US-TKT-001, US-TKT-006

FR-TKT-008 — Trigger the configurable escalation ladder on SLA breach [M]

Description. The system must escalate tickets up the ladder (Staff/POC → add DG as watcher → add Department Secretary → notify S&ITD Secretary/SACM) as each SLA threshold is crossed, with oversight powers configurable per department.

Rationale. Locked escalation ladder (_context.md §5); ensures stalled tickets surface to leadership.

Acceptance criteria.

• At the configured threshold (default 2 days), the DG is added as watcher and notified.
• At the next threshold (default +5 days), the Department Secretary is added as watcher and notified.
• At the final threshold (default +10 days total), S&ITD Secretary / SACM is notified.
• Each tier's oversight power (notify-only vs action) is enforced per the department's configuration.
• The same ladder applies inside S&ITD itself.
• Thresholds are configurable per department/category/urgency.
• Every escalation event is audit-logged.

Traces to. US-TKT-006, US-ORG-005

FR-TKT-009 — Enforce the proof-of-resolution gate before Resolved [M]

Description. The system must block any transition to Resolved unless at least one evidence attachment and a resolution note are present.

Rationale. Locked resolution-proof gate (_context.md §5); ensures closures are evidence-backed.

Acceptance criteria.

• The Resolved transition is rejected when fewer than one evidence attachment is present.
• The Resolved transition is rejected when the resolution note is empty.
• The system states which required item is missing on rejection.
• The gate is not bypassable by any role except via an explicit, audited override available to designated approvers only.

Traces to. US-TKT-006

FR-TKT-010 — Auto-close resolved tickets after the CSAT window [M]

Description. The system must automatically transition a Resolved ticket to Closed when the CSAT window elapses without company action, or upon the company's explicit acceptance.

Rationale. Locked auto-close behaviour (_context.md §5); prevents tickets from lingering.

Acceptance criteria.

• A Resolved ticket transitions to Closed automatically at the configured CSAT window expiry.
• The company may accept early, triggering immediate closure.
• The closure event, timestamp, and trigger (auto vs accepted) are recorded.
• A Closed ticket is locked from public comment but may be appealed or reopened per policy.

Traces to. US-TKT-006

FR-TKT-011 — Reopen on company rejection of resolution [M]

Description. The system must let the Company Representative reject a Resolved ticket within the CSAT window, returning it to its prior working state and resuming the SLA clock per policy.

Rationale. Locked reopen behaviour (_context.md §5); preserves the company's voice.

Acceptance criteria.

• A reject action is available to the filer within the CSAT window.
• On reject, the ticket returns to its prior working status.
• The SLA clock resumes according to policy (counting time elapsed prior to resolve).
• Assigned staff and watchers are notified of the reopen with the rejection reason.

Traces to. US-TKT-006

FR-TKT-012 — Allow appeal of a closed ticket [M]

Description. The system must let the Company Representative file an appeal against a Closed ticket, creating an appeal record routed to the next escalation tier, and link the original ticket as Under Appeal.

Rationale. Locked appeal behaviour (_context.md §5, modelled on CPGRAMS).

Acceptance criteria.

• An appeal action is available on Closed tickets within the configured appeal window.
• The appeal is routed to the next escalation tier.
• The original ticket is linked and marked Under Appeal.
• The appeal record preserves the original resolution, evidence, and reason for appeal.
• Appeal outcome (upheld / overturned / remanded) is recorded on the ticket history.

Traces to. US-TKT-006

FR-TKT-013 — Collect Customer Satisfaction (CSAT) feedback [M]

Description. The system must collect a CSAT rating and optional free-text feedback from the filer after a ticket is Resolved, and store it on the ticket for analytics.

Rationale. CSAT is one of the 9 analytics metric families (quality/outcome) and supports the auto-close flow.

Acceptance criteria.

• A CSAT prompt is sent to the filer on transition to Resolved.
• The rating scale and free-text field are configurable.
• A non-response after the window counts as implicit acceptance (per auto-close) but is recorded distinctly from explicit acceptance.
• CSAT responses are surfaced in analytics and on staff/department dashboards (aggregate, not individual where policy requires).

Traces to. US-TKT-006, US-ANL-001

FR-TKT-014 — Decompose a parent ticket into sub-tasks [S]

Description. The system must let a facilitator split a parent ticket into sub-tasks, each with its own assignee, status, and SLA, and prevent the parent from closing until all sub-tasks are resolved or explicitly waived.

Rationale. Locked sub-task behaviour (_context.md §4 module B).

Acceptance criteria.

• A facilitator can create sub-tasks from a parent ticket with independent assignee/status/SLA.
• The parent's roll-up status reflects its sub-tasks.
• The parent cannot be Resolved while open sub-tasks remain, unless each is explicitly waived with reason.
• Sub-tasks inherit category/department from the parent by default and can be reassigned.
• The parent–subtask relationship is visible on both views.

Traces to. US-TKT-005

FR-TKT-015 — Merge duplicate tickets into a primary [S]

Description. The system must let a facilitator merge two or more duplicate tickets (same company, same underlying issue) into a primary, locking the secondaries and consolidating attachments, comments, and watchers.

Rationale. Locked merge behaviour (_context.md §4 module B); supports dedup at scale.

Acceptance criteria.

• Merge is offered on tickets from the same company flagged as duplicates by AI or facilitator.
• Secondary tickets are marked Merged into <primary ID> and locked from further updates.
• Attachments, comments, and watchers consolidate onto the primary.
• The merge action and actor are audit-logged.
• The filer is notified with the new primary ID for tracking.

Traces to. US-TKT-005

FR-TKT-016 — Split a ticket with distinct issues [S]

Description. The system must let a facilitator split a single ticket that contains multiple distinct issues into separate tickets, preserving source attribution.

Rationale. Locked split behaviour (_context.md §4 module B).

Acceptance criteria.

• A facilitator can select content (description excerpt, comments, attachments) to move into a new ticket.
• The new ticket references the original as Split from <original ID>.
• Both tickets retain their own SLA and assignee.
• The split action is audit-logged.

Traces to. US-TKT-005

FR-TKT-017 — Link/relate tickets across departments [S]

Description. The system must let a facilitator link or relate tickets (e.g., "blocked by", "duplicate of", "related to") across departments, surfacing links on each linked ticket.

Rationale. Real-world issues span departments; linkages preserve context (US-TKT-005).

Acceptance criteria.

• A facilitator can create a typed link between two tickets with a relation label.
• Links are visible on both linked tickets.
• Cross-department links respect each department's access policy.
• Links are audit-logged.

Traces to. US-TKT-005

FR-TKT-018 — Add watchers and CCs to a ticket [S]

Description. The system must let authorized staff add watchers and CCs to a ticket, with watchers receiving ongoing notifications and CCs receiving one-time notification.

Rationale. Locked watchers/CC behaviour (_context.md §4 module B); supports oversight.

Acceptance criteria.

• Watchers receive ongoing notifications on ticket events per their preferences.
• CCs receive a one-time notification of being added.
• Watchers/CCs can be added and removed by authorized staff.
• Watcher/CC changes are audit-logged.
• Escalation-tier additions (DG, Secretary) are recorded as watcher additions.

Traces to. US-TKT-005

FR-TKT-019 — Apply bulk actions to a filtered selection [S]

Description. The system must let a facilitator apply a bulk action (e.g., assign, change priority, change category, escalate, close) to a filtered selection of tickets.

Rationale. Locked bulk behaviour (_context.md §4 module B); operational efficiency.

Acceptance criteria.

• Bulk actions are offered on filtered ticket lists.
• Each affected ticket records the action and actor in its history.
• Bulk actions respect the user's permissions on every ticket in the selection; failures are reported per ticket.
• Bulk actions are audit-logged as a single batch with affected ticket IDs.

Traces to. US-TKT-005

FR-TKT-020 — Enforce confidential/VIP attribute-based access control [M]

Description. The system must restrict access to tickets marked Confidential or VIP to staff holding the matching attribute, hiding such tickets from unauthorized users in lists and search.

Rationale. Locked ABAC decision (_context.md §5, US-ORG-007); defense in depth.

Acceptance criteria.

• A ticket can be marked Confidential or VIP by authorized staff.
• Unauthorized users cannot open, list, or search such tickets; access attempts are denied and logged.
• The mark gates downstream features (e.g., MoM approval, export).
• The Sensitive/VIP proof-of-resolution closure may require Chair/DG approval (per _context.md §5).

Traces to. US-ORG-007, US-TKT-006

FR-TKT-021 — Surface similar tickets for deflection at compose time [S]

Description. While a representative composes a draft, the system must surface similar resolved or open tickets and let them discard the draft if a resolved ticket answers their issue.

Rationale. Locked smart-filing-assistant behaviour (US-TKT-004); reduces avoidable tickets.

Acceptance criteria.

• With at least a title and description present, similar tickets are listed with similarity scores.
• The representative can accept a similar resolved ticket as their answer and discard the draft in one action.
• The deflection event is recorded for analytics.
• Similarity uses AI capability FR-AI-007 and respects access scope.

Traces to. US-TKT-004, US-AI-005

ORG — Organization & RBAC

Epic E3. Company registration (5 entity types), file-first/verify-in-parallel, multi-rep with exactly one Primary, granular RBAC, nested departments with DG/Secretary oversight, automated lifecycle, step-up auth, ABAC for confidential/VIP, exam-gate. Traces to US-ORG-001 … US-ORG-007. RBAC detail in /specs/en/04-roles-permissions/.

FR-ORG-001 — Render a conditional registration form per entity type [M]

Description. The system must render a registration form that adapts to the selected entity type (SECP company, sole proprietor/partnership, freelancer/individual, foreign branch, early startup provisional), showing and validating only the fields and documents applicable to that type, and always collecting the Primary Authorized Rep as a mandatory role.

Rationale. Locked 5-entity-type decision (_context.md §5).

Acceptance criteria.

• The five entity types are selectable; selecting one re-renders the form for that type.
• Only the fields and document requirements applicable to the type are shown and validated.
• The Primary Authorized Rep role is collected as mandatory on every registration.
• The form is multilingual with RTL support for UR/SD.

Traces to. US-ORG-001

FR-ORG-002 — Grant a Provisional account on registration that can file immediately [M]

Description. The system must grant a Provisional account immediately on registration acceptance, displaying a Provisional badge, allowing ticket filing without delay, and queueing background verifications in parallel.

Rationale. Locked file-first/verify-in-parallel decision (_context.md §5).

Acceptance criteria.

• A registration that passes initial validation immediately creates a Provisional account.
• The account displays a Provisional badge in the UI.
• The Provisional account can file tickets immediately.
• Background verifications (SECP/FBR/SRB/PSEB/NADRA + domain email) are queued in parallel via the INT module.
• The company is notified of verification progress.

Traces to. US-ORG-002

FR-ORG-003 — Transition badge based on verification outcome [M]

Description. The system must transition the company badge from Provisional to Verified when all checks pass, or to On Hold when any check fails, and offer an appeal path on failure.

Rationale. Locked verify-in-parallel behaviour (_context.md §5).

Acceptance criteria.

• All-checks-pass transitions the badge to Verified and notifies the company.
• Any-check-fail transitions the badge to On Hold and notifies the company with the reason.
• A failed verification offers an appeal submission with supporting evidence routed to S&ITD for adjudication.
• The transition and reason are audit-logged.

Traces to. US-ORG-002

FR-ORG-004 — Manage multiple representatives with exactly one Primary [M]

Description. The system must let a company administrator add multiple authorized representatives (each with CNIC and domain email) and designate exactly one as Primary Authorized Rep, with the Primary role being mandatory at all times and transferable.

Rationale. Locked multi-rep decision (_context.md §5).

Acceptance criteria.

• A company administrator can add representatives with CNIC and domain email.
• Each new representative receives an invitation and must accept before gaining access.
• Exactly one representative is Primary at all times; the invariant is enforced by the system.
• The administrator can transfer the Primary role; the prior Primary becomes a regular representative.
• All Primary changes are audit-logged.

Traces to. US-ORG-003

FR-ORG-005 — Apply role templates with granular per-permission overrides [M]

Description. The system must apply role templates (Primary, Admin, Filer, Viewer, Notify) to representatives and department staff, and allow administrators to override individual permissions on top of the template, with an explicit deny always prevailing over a template grant.

Rationale. Locked RBAC decision (_context.md §5).

Acceptance criteria.

• Role templates can be assigned; assignment grants every permission in the template.
• An administrator can toggle individual permissions to override the template.
• The user's effective permission set is the template adjusted by overrides.
• An explicit deny prevails over any template grant.
• Every override and actor is audit-logged.

Traces to. US-ORG-004

FR-ORG-006 — Model departments as Department → Section → Staff with DG/Secretary oversight [M]

Description. The system must model government departments as a hierarchy (Department → Section → Staff) and allow assignment of DG and Secretary oversight roles to each department.

Rationale. Locked nested-departments decision (_context.md §4 module C); enables routing and oversight.

Acceptance criteria.

• A Portal administrator can create a department and one or more sections under it.
• Staff are assigned to sections/departments.
• DG and Secretary oversight roles are assignable per department.
• The hierarchy is reflected in routing, reporting, and the escalation ladder.

Traces to. US-ORG-005

FR-ORG-007 — Notify oversight roles per escalation tier with configurable powers [M]

Description. When a ticket breaches a configured escalation threshold, the system must add the relevant DG or Secretary as a watcher and notify them, enforcing their oversight power (notify-only vs action) per the department's configuration.

Rationale. Locked escalation ladder with configurable oversight (_context.md §5).

Acceptance criteria.

• At each threshold, the relevant oversight role is added as watcher and notified.
• Oversight power (notify-only vs action) is enforced per department configuration.
• Notify-only oversight roles cannot reassign or close tickets; action roles can.
• Escalation events are audit-logged.

Traces to. US-ORG-005, US-TKT-008

FR-ORG-008 — Automate account lifecycle on material events [M]

Description. The system must automatically deactivate or re-verify accounts when material events occur (Primary rep transfer, representative change, company struck-off by SECP), reassigning or pausing open tickets per policy.

Rationale. Locked account-lifecycle automation (_context.md §4 module C).

Acceptance criteria.

• Primary rep transfer deactivates the previous rep and notifies the company.
• Authorized representative change triggers re-verification of the new rep.
• SECP strike-off deactivates the company account.
• Open tickets are reassigned or paused per policy.
• All lifecycle actions are audit-logged.

Traces to. US-ORG-006

FR-ORG-009 — Require step-up authentication for sensitive actions [S]

Description. The system must require a second authentication factor for sensitive actions (e.g., closing a VIP ticket, exporting bulk PII, changing Primary rep), proceeding only after successful step-up.

Rationale. Locked step-up-auth decision (_context.md §5).

Acceptance criteria.

• Sensitive actions are tagged in the permission model.
• Invoking a sensitive action with a standard session challenges the user for a second factor.
• The action proceeds only after successful step-up.
• The step-up event is audit-logged.
• The session is marked step-up-authenticated for the configured window.

Traces to. US-ORG-007

FR-ORG-010 — Enforce exam-gate before live ticket handling [S]

Description. The system must prevent any staff member who has not passed the required certification exam from taking ownership of a live ticket, surfacing the gate status to their supervisor.

Rationale. Locked exam-gate decision (_context.md §4 module O).

Acceptance criteria.

• Auto-routing and manual assignment are blocked for uncertified staff with an explanatory message.
• The gate status (certified / pending / expired) is visible to the staff member and their supervisor.
• Passing the certification exam (TRN module) unblocks assignment.
• Expiry of certification re-applies the gate (per FR-TRN-005).

Traces to. US-ORG-007, US-TRN-002

FILE — Files

Epic E4. Secure uploads with AV scan, encrypted storage, in-app preview, versioning, time-limited download links, size/type limits, retention linkage. Traces to US-FILE-001 … US-FILE-005.

FR-FILE-001 — Enforce file size and type limits [M]

Description. The system must enforce per-file and per-submission size and MIME-type limits on uploads, rejecting out-of-policy files with a specific message.

Rationale. Protects storage and downstream pipelines; locked behaviour (US-FILE-001).

Acceptance criteria.

• Per-file size limit and per-submission total size limit are enforced server-side.
• Allowed MIME types are enforced (e.g., PDF, common image, Office formats); executables and unknown types are rejected.
• Rejection message names the specific limit violated.
• Limits are configurable per upload context (ticket attachment, MoM, registration document).

Traces to. US-FILE-001

FR-FILE-002 — Accept uploads from both sides (requester and staff) [M]

Description. The system must allow both company representatives and staff to upload files in the contexts they are authorized for (intake, comments, resolution evidence, MoM, registration documents).

Rationale. Locked "both sides" upload behaviour (_context.md §4 module D).

Acceptance criteria.

• Company representatives can upload in authorized contexts (intake, comments, registration).
• Staff can upload in authorized contexts (comments, resolution evidence, MoM, official documents).
• Each upload is attributed to the uploader with a timestamp.
• Uploads outside an authorized context are denied.

Traces to. US-FILE-001

FR-FILE-003 — Scan every upload with ClamAV and quarantine on detection [M]

Description. The system must scan every uploaded file with ClamAV before it is made available for use, quarantining and rejecting malicious files, and raising a security alert.

Rationale. Locked AV-scan decision (_context.md §3, §4 module D).

Acceptance criteria.

• Every upload is scanned by ClamAV before being made available for download or preview.
• A clean file proceeds to encrypted storage.
• An infected file is quarantined, not made available, and the upload is rejected with a safe message.
• A security alert is raised and the event is audit-logged.
• Scan failures (ClamAV down) fail safe: file is held pending scan, not served.

Traces to. US-FILE-002

FR-FILE-004 — Store files encrypted in object storage [M]

Description. The system must store all uploaded files encrypted at rest in S3-compatible object storage (MinIO), with a stored record linking the file to its owning ticket/comment and uploader.

Rationale. Locked encrypted-storage decision (_context.md §3, §4 module D).

Acceptance criteria.

• Files are written to MinIO encrypted at rest.
• A metadata record links each file to its owner (ticket, comment, registration, MoM) and uploader.
• Decryption keys are managed via the configured secrets store.
• Files are inaccessible via direct storage path; only the application can serve them.

Traces to. US-FILE-002

FR-FILE-005 — Provide in-app preview for supported formats [S]

Description. The system must provide an in-app preview for supported file formats (PDF, common image, plain text, Office where supported) without requiring a download, gated by access.

Rationale. Improves review efficiency (US-FILE-003).

Acceptance criteria.

• A preview action is available on supported formats.
• The preview renders inline without a separate download.
• Users without access cannot preview.
• Unsupported formats fall back to download (where permitted).

Traces to. US-FILE-003

FR-FILE-006 — Version files on re-upload [S]

Description. When a new version of an existing file is uploaded, the system must preserve the prior version as history, mark the new one as current, and record version number, uploader, and timestamp.

Rationale. Locked versioning behaviour (_context.md §4 module D); preserves evidence integrity.

Acceptance criteria.

• A re-upload of an existing file creates a new version rather than overwriting.
• Prior versions are preserved and accessible to authorized users.
• The latest version is shown as current.
• Version number, uploader identity, and timestamp are recorded per version.
• Version history is audit-logged.

Traces to. US-FILE-003

FR-FILE-007 — Generate signed, time-limited download links [M]

Description. The system must generate signed, expiring download links for files, valid only within their time limit and from allowed contexts, with every download audit-logged.

Rationale. Locked secure-download-links behaviour (_context.md §4 module D); avoids exposing storage.

Acceptance criteria.

• A staff member can generate a signed download link with a configurable time limit.
• The link downloads the file successfully within its limit and from allowed contexts.
• An expired or tampered link is rejected with an "expired or invalid" response.
• Every download (successful and failed) is audit-logged.

Traces to. US-FILE-004

FR-FILE-008 — Associate each file with a retention policy [S]

Description. The system must associate each file with a retention policy (based on its category and document type, aligned with Sindh Archives rules), executing archive or purge actions on schedule.

Rationale. Locked retention behaviour (_context.md §4 module D, §6).

Acceptance criteria.

• A retention policy is associated with each file based on its category and document type.
• The policy is visible to records officers.
• A scheduled job archives or purges files at their retention horizon.
• Retention actions are recorded for compliance audit.

Traces to. US-FILE-005

AI — AI (11 Capabilities, Pluggable Engine)

Epic E5. The eleven locked AI capabilities behind a single pluggable-engine abstraction with per-feature flags and cost logging. Traces to US-AI-001 … US-AI-007. Full spec in /specs/en/07-ai-ocr-spec/. AI augments human accountability; it never replaces a human decision gate.

FR-AI-001 — Multilingual OCR (EN/UR/SD) [M]

Description. The system must run OCR on uploaded scanned documents in English, Urdu, and Sindhi scripts, producing searchable indexed text with a confidence score, and flagging low-confidence extractions for manual review.

Rationale. Locked AI capability #1 (OCR, _context.md §4 module E); unlocks search/summary/translation downstream.

Acceptance criteria.

• OCR runs on uploaded scanned documents (images, PDFs) automatically or on demand.
• Text is extracted for Latin, Urdu, and Sindhi scripts.
• Extracted text is indexed for full-text search.
• A confidence score is attached to each extraction.
• Low-confidence extractions are flagged for manual review.

Traces to. US-AI-001

FR-AI-002 — Produce a ticket summary on intake [M]

Description. The system must produce a concise summary of each new ticket at intake, attached to the ticket for officer review.

Rationale. Locked AI capability #2 (summary, _context.md §4 module E).

Acceptance criteria.

• A summary is generated for each new ticket asynchronously after submission.
• The summary is concise (configurable length) and human-reviewable.
• The summary is visible in the triage and ticket detail views.
• Generation failures do not block ticket creation.

Traces to. US-AI-002

FR-AI-003 — Classify and suggest routing on intake [M]

Description. The system must classify each new ticket and suggest department, section, and urgency, with a confidence score, for officer review.

Rationale. Locked AI capability #3 (classification/auto-routing, _context.md §4 module E).

Acceptance criteria.

• Classification (category) and routing suggestion (department, section, urgency) are produced at intake.
• Each suggestion carries a confidence score.
• Officer override is audit-logged with the original suggestion and the actor.

Traces to. US-AI-002, US-TKT-005

FR-AI-004 — Score urgency and sentiment [S]

Description. The system must score each ticket for urgency and sentiment at intake and on update, surfacing high-urgency items in the triage queue.

Rationale. Locked AI capability #4 (urgency/sentiment, _context.md §4 module E).

Acceptance criteria.

• Urgency level and sentiment label are computed at intake and on meaningful updates.
• High-urgency tickets are surfaced in the triage queue.
• Critical-urgency tickets are routed to the appropriate SLA tier per policy with rationale visible to the officer.

Traces to. US-AI-003

FR-AI-005 — Draft context-aware replies for staff [S]

Description. The system must produce a context-aware draft reply on staff request, clearly marked as AI-generated, with explicit human confirmation required to send.

Rationale. Locked AI capability #5 (draft replies, _context.md §4 module E).

Acceptance criteria.

• A draft reply can be requested by staff on any ticket needing a response.
• The draft is context-aware (ticket history, prior replies, KB).
• The draft is visually marked AI-generated until edited or approved.
• Sending requires explicit human confirmation; AI cannot send autonomously.

Traces to. US-AI-004

FR-AI-006 — Translate messages and content across EN/UR/SD [S]

Description. The system must translate messages and content between EN, UR, and SD on request, showing the translation alongside the original (which is preserved unchanged).

Rationale. Locked AI capability #6 (translation, _context.md §4 module E).

Acceptance criteria.

• Translation is offered on messages and content between any pair of EN/UR/SD.
• The translation is shown alongside the original.
• The original is preserved unchanged.
• The translation is marked as machine-generated.

Traces to. US-AI-004

FR-AI-007 — Detect duplicates and similar tickets [S]

Description. The system must detect duplicate and similar tickets at intake and triage, surfacing them with similarity scores for link, merge, or deflection.

Rationale. Locked AI capability #7 (duplicate/similarity, _context.md §4 module E).

Acceptance criteria.

• Similar open and resolved tickets are surfaced at intake and in triage with similarity scores.
• Facilitators can link, merge, or use them for deflection.
• The similarity service respects access scope (Confidential/VIP).

Traces to. US-AI-005, US-TKT-021

FR-AI-008 — Run the public chatbot with human handoff [S]

Description. The system must run a public AI chatbot that answers from approved knowledge sources in the visitor's language, with human handoff and ticket-draft pre-fill.

Rationale. Locked AI capability #8 (chatbot, _context.md §4 module E).

Acceptance criteria.

• The chatbot answers from approved knowledge sources in the visitor's language.
• Answers cite the source article/FAQ.
• Confidence-threshold handoff to a live facilitator is supported with transcript attachment.
• Pre-fill of a ticket draft is supported (see FR-PUB-004).

Traces to. US-AI-006, US-PUB-004

FR-AI-009 — Redact PII before any cloud AI processing [M]

Description. Before any document or message leaves the on-prem trust boundary for cloud AI processing, the system must detect and mask/tokenize PII (CNIC, phone, email, etc.), retaining a redaction map on-prem so the original can be restored on return.

Rationale. Locked AI capability #9 (PII redaction, _context.md §4 module E); privacy protection.

Acceptance criteria.

• PII (CNIC, phone, email, and other configured patterns) is detected in outbound payloads.
• Detected PII is masked or tokenized before the payload leaves the trust boundary.
• A redaction map is retained on-prem to restore the original on return.
• The redaction step is audit-logged.
• For self-hosted engine configurations, redaction is still applied for defense in depth.

Traces to. US-AI-005

FR-AI-010 — Generate AI-driven trends and analytics insights [S]

Description. The system must generate AI-driven trend insights (rising categories, bottleneck departments) from ticket data, surfaced on leadership analytics, each insight linking to the underlying metric.

Rationale. Locked AI capability #10 (trends/analytics, _context.md §4 module E).

Acceptance criteria.

• Trend insights are generated on a configurable schedule from ticket data.
• Insights include category rises/falls, bottleneck departments, and other configured patterns.
• Each insight links to the underlying metric for drill-down.
• Insights are surfaced to leadership roles per their scope.

Traces to. US-AI-006, US-ANL-001

FR-AI-011 — Extract MoM action items via OCR + AI [M]

Description. The system must extract structured action items (owner, due date, text) and a summary from uploaded Minutes of Meeting documents via OCR + AI, presenting them for officer confirmation.

Rationale. Locked AI capability #11 (MoM action-item extraction, _context.md §4 module E, §5).

Acceptance criteria.

• Uploaded MoM (scanned or text) is processed by OCR (multilingual) then AI.
• Action items with owner, due date, and text are extracted for officer review.
• A summary is produced.
• The officer can edit/remove/add items before confirmation.
• Confirmed items become ticket sub-tasks (per FR-MTG-007).

Traces to. US-AI-006, US-MTG-003

FR-AI-012 — Abstract all capabilities behind a pluggable engine interface [M]

Description. The system must expose all AI capabilities behind a single pluggable-engine abstraction so that operators can swap providers (LLM: Azure OpenAI/Google/AWS or self-hosted Llama/Qwen via Ollama + vLLM; OCR: Tesseract/Google Doc AI/Azure Document Intelligence/AWS Textract) without code changes.

Rationale. Locked pluggable-engine policy (_context.md §4, §3).

Acceptance criteria.

• Each AI capability is exposed through a single interface.
• Engine selection per capability is configurable at runtime without code changes.
• Switching engines does not change the calling code path or contract.
• Both cloud and self-hosted engines are supported for each capability.

Traces to. US-AI-007

FR-AI-013 — Gate each capability behind a per-feature flag [M]

Description. Each AI capability must be independently toggleable via a feature flag, degrading gracefully (hidden or controlled "unavailable" response) when disabled, without exposing errors to end users.

Rationale. Locked per-feature-flag decision (_context.md §4 module Q).

Acceptance criteria.

• Each AI capability has its own feature flag.
• Disabling a flag hides or returns a controlled "unavailable" response.
• Dependent flows degrade gracefully.
• No error is exposed to end users.
• Flag state is audit-logged (per FFG module).

Traces to. US-AI-007, US-FFG-001

FR-AI-014 — Log cost and usage per AI invocation [S]

Description. The system must log token/credit cost, engine, capability, requester, and latency for each AI invocation, exposing usage and cost in analytics.

Rationale. Pluggable engines incur variable cost; locked observability expectations (_context.md §3).

Acceptance criteria.

• Each AI invocation logs: capability, engine, tokens/units, cost estimate, latency, requester, timestamp.
• Cost and usage are aggregated and surfaced in analytics dashboards.
• Cost overruns on a capability trigger a configurable alert.

Traces to. US-AI-007, US-ANL-001

COM — Internal Communications (Three Tiers)

Epic E6. Three escalating tiers: (1) ticket-scoped private threads, (2) org-wide inbox (DMs/groups), (3) channel-based chat. @mentions, presence, full-text search, retention. All staff-only. Traces to US-COM-001 … US-COM-005.

FR-COM-001 — Provide ticket-scoped private threads [M]

Description. The system must provide a private discussion thread attached to each ticket, visible only to ticket participants, supporting messages with @mentions and attachments, retained with the ticket record.

Rationale. Locked Tier-1 decision (_context.md §4 module F).

Acceptance criteria.

• Each ticket has a private thread scoped to its participants.
• Messages support @mentions (with notification) and attachments.
• Messages are visible only to current ticket participants.
• Thread messages are not visible from other tickets or from Tiers 2/3.
• If a participant's access is revoked, their view of the thread is removed.

Traces to. US-COM-001

FR-COM-002 — Notify @mentioned participants in ticket threads [M]

Description. The system must notify @mentioned participants in ticket-scoped threads, sending the notification via the user's preferred channels per their preferences.

Rationale. Ensures timely coordination (US-COM-001).

Acceptance criteria.

• An @mention triggers a notification to the mentioned user.
• Notifications are routed via the NOT module per the user's preferences.
• Mentions support both individual users and configured roles/groups.

Traces to. US-COM-001

FR-COM-003 — Provide org-wide inbox (1:1 and group DMs) [S]

Description. The system must provide an org-wide inbox for one-to-one and group direct messages between any staff (officer, DG, Secretary), with new-participant history governed by a configured policy.

Rationale. Locked Tier-2 decision (_context.md §4 module F).

Acceptance criteria.

• A staff member can start a 1:1 or group DM with any other staff across departments.
• Only named participants can see the conversation.
• Adding a new participant follows the configured history-sharing policy (full history or from-join).
• All messages are retained and audit-logged.

Traces to. US-COM-002

FR-COM-004 — Provide persistent department/ad-hoc channels with threads and pins [C]

Description. The system must provide persistent channels per department or topic, plus ad-hoc channels, with threaded replies, pinned messages, and auto-join for department members.

Rationale. Locked Tier-3 decision (_context.md §4 module F).

Acceptance criteria.

• An administrator can create department and ad-hoc channels.
• Department members are auto-joined to their department channel; others can request to join per policy.
• Channel messages support threaded replies grouped under the parent.
• Pinned messages appear in the channel's pinned list.
• Channel operations are audit-logged.

Traces to. US-COM-003

FR-COM-005 — Support @role mentions in channels and DMs [S]

Description. The system must support @role mentions (e.g., @officers, @dg) that notify all members of that role in the context.

Rationale. Operational efficiency for group addressing (US-COM-003, US-COM-004).

Acceptance criteria.

• @role mentions are parsed and expanded to the role's current members.
• Each expanded member receives a notification per their preferences.
• Role membership is resolved at mention time.

Traces to. US-COM-003, US-COM-004

FR-COM-006 — Provide presence, typing, and read receipts [S]

Description. The system must show real-time presence (online/away), typing indicators, and read receipts within active conversations.

Rationale. Real-time communication expectations (US-COM-004).

Acceptance criteria.

• Presence shows each participant's online/away status in real time.
• Typing indicators reflect participant activity in real time.
• Read receipts reflect message-read state in real time.
• A user may suppress their own indicators in their preferences.

Traces to. US-COM-004

FR-COM-007 — Provide multilingual full-text search across accessible messages [S]

Description. The system must provide full-text search across the user's accessible messages (channels, DMs, threads), correctly matching Urdu and Sindhi keywords via the multilingual search engine.

Rationale. Locked Tier-3 search requirement (US-COM-004).

Acceptance criteria.

• Search returns only messages the user can access.
• Urdu and Sindhi keywords match correctly (no transliteration loss).
• Results are ranked by relevance with snippet and source link.
• Search is gated by access scope (Confidential/VIP tickets invisible).

Traces to. US-COM-004, FR-XCU-002

FR-COM-008 — Audit-log and retain all messages per policy [M]

Description. The system must audit-log every message at send time (sender, recipients, timestamp, channel/ticket, content hash) immutably, and retain/archive messages per the records policy.

Rationale. Locked retention and audit requirement (_context.md §4 module F, §6).

Acceptance criteria.

• An audit record is written at send time for every message in any tier.
• The audit record captures sender, recipients, timestamp, channel/ticket, and content hash.
• The record cannot be altered by the sender.
• Retention horizons per tier trigger archive or purge per policy.
• Retention actions are logged for compliance.

Traces to. US-COM-005

NOT — Notifications

Epic E7. Templated multilingual notifications across Email/SMS/WhatsApp/in-app, two-way inbound replies, preference center, rate limiting. Traces to US-NOT-001 … US-NOT-005.

FR-NOT-001 — Deliver notifications across email, SMS, WhatsApp, and in-app [M]

Description. The system must deliver notifications across email (Mailjet), SMS, WhatsApp, and in-app channels, respecting the user's enabled channels, with retry and fallback.

Rationale. Locked multichannel decision (_context.md §3, §4 module G).

Acceptance criteria.

• Each notification event is delivered via every channel the user has enabled.
• Delivery status (sent, delivered, failed) is recorded per channel.
• On primary-channel failure, the system retries per policy, then attempts a configured fallback channel.
• Failures and fallbacks are logged.

Traces to. US-NOT-001

FR-NOT-002 — Render notifications from versioned, multilingual templates [M]

Description. The system must render every notification from versioned templates in EN, UR, and SD, in the recipient's preferred language, with correct variable substitution and Gregorian + Hijri dates.

Rationale. Locked templated/multilingual decision (_context.md §2, §4 module G).

Acceptance criteria.

• Templates exist in EN, UR, SD for every notification event.
• The recipient's preferred language selects the template variant.
• Variables (ticket ID, names, dates) are substituted correctly.
• Dates display in both Gregorian and Hijri per convention.
• Template edits create new versions; prior versions are preserved.
• The editor and timestamp of a template change are recorded.

Traces to. US-NOT-002

FR-NOT-003 — Accept two-way inbound replies that append to tickets [S]

Description. The system must accept inbound replies by email and WhatsApp to a notification, append the reply body and attachments as a comment on the originating ticket, and hold unmatched inbound for facilitator review.

Rationale. Locked two-way inbound decision (_context.md §4 module G).

Acceptance criteria.

• An email reply to a ticket notification appends the body and attachments as a comment on the originating ticket.
• A WhatsApp reply similarly appends.
• Assigned staff and watchers are notified of the append.
• The append event is logged.
• An unmatched inbound (no ticket or sender resolution) is held for review and a facilitator is notified.

Traces to. US-NOT-003

FR-NOT-004 — Provide a per-user preference center [M]

Description. The system must provide a preference center where each user configures digest cadence, quiet hours, and per-channel opt-outs, with urgent events bypassing quiet hours per policy.

Rationale. Locked preference-center decision (_context.md §4 module G).

Acceptance criteria.

• A user can choose a digest (daily/weekly) for non-urgent events.
• Urgent events bypass the digest and send immediately.
• A user can configure quiet hours; non-urgent notifications are held until quiet hours end.
• Urgent notifications bypass quiet hours per policy.
• A user can opt out of any channel; opted-out channels are not used.
• All preference changes are logged.

Traces to. US-NOT-004

FR-NOT-005 — Rate-limit outbound and inbound notifications [M]

Description. The system must rate-limit outbound notifications to protect channels (per recipient and per domain) and throttle inbound abuse from a single source, flagging repeated inbound for review.

Rationale. Locked rate-limit decision (_context.md §4 module G).

Acceptance criteria.

• Outbound rate limits per recipient and per domain are enforced; excess is queued or coalesced.
• No provider rate cap is breached.
• Inbound from a single source exceeding the threshold is throttled.
• Throttled inbound is flagged for review.

Traces to. US-NOT-005

FR-NOT-006 — Capture notification delivery and engagement metrics [S]

Description. The system must capture per-notification delivery and engagement (open, click) metrics and expose them in analytics.

Rationale. Supports analytics metric family (engagement/comms) and template-effectiveness review.

Acceptance criteria.

• Per-notification delivery status (sent, delivered, bounced) is recorded per channel.
• Open and click engagement is captured where the channel supports it.
• Metrics are aggregated into analytics dashboards.
• Failures and bounces trigger corrective action per policy.

Traces to. US-NOT-001, US-ANL-001

INT — Integrations

Epic E8. NADRA, SECP, FBR, SRB, PSEB, NITB e-Office, OIDC SSO, public REST API + outbound webhooks, all behind an adapter pattern with idempotency, retries, and circuit breakers. Traces to US-INT-001 … US-INT-005. Contracts in /specs/en/08-integrations-spec/, /specs/en/12-api-contract/.

FR-INT-001 — Verify CNIC against NADRA via an adapter [M]

Description. The system must verify a representative's CNIC against NADRA through a NADRA adapter, returning a deterministic verified/not-verified/unable-to-verify result, degrading gracefully via a circuit breaker on outage.

Rationale. Locked NADRA decision (_context.md §4 module H).

Acceptance criteria.

• The NADRA adapter returns a deterministic result for a supplied CNIC.
• The result, timestamp, and request reference are stored on the representative's record.
• On NADRA outage, the circuit breaker opens after configured failures.
• The registration flow places the account in verification pending and resumes on recovery.

Traces to. US-INT-001

FR-INT-002 — Look up company status across SECP, FBR/NTN, SRB, and PSEB via adapters [M]

Description. The system must look up company registration, tax, and industry-body status across SECP, FBR/NTN, SRB, and PSEB through per-registry adapters, storing normalized results and flagging conflicts for manual review.

Rationale. Locked multi-registry decision (_context.md §4 module H); feeds file-first/verify-in-parallel.

Acceptance criteria.

• Each registry adapter returns a normalized lookup result.
• Results feed the parallel verification workflow.
• Conflicting statuses across registries flag the verification for manual review.
• Discrepancies are visible to the adjudicator.

Traces to. US-INT-002, US-ORG-002

FR-INT-003 — Move tickets and MoMs into NITB e-Office [S]

Description. The system must create a file movement in NITB e-Office for resolved tickets and published MoMs (where the integration is enabled for the department), storing the e-Office reference on the ticket/MoM, queueing and retrying on outage without blocking the Portal.

Rationale. Locked e-Office integration (_context.md §4 module H, §6).

Acceptance criteria.

• A resolved ticket with proof-of-resolution triggers an e-Office file movement when enabled for the department.
• The e-Office reference is stored on the ticket.
• The creation is audit-logged.
• On outage, the movement is queued and retried; the Portal flow is not blocked.
• Recovery reconciles pending movements idempotently.

Traces to. US-INT-003

FR-INT-004 — Provide OIDC single sign-on for government staff [M]

Description. The system must provide OIDC single sign-on for government staff via the department identity provider, applying group and role claims, with step-up 2FA for sensitive sessions per provider policy.

Rationale. Locked SSO decision (_context.md §3, §4 module H).

Acceptance criteria.

• Staff can sign in via OIDC through the department identity provider.
• On successful authentication, group and role claims are applied to the session.
• Sensitive sessions require a second factor per provider policy.
• The session is marked step-up-authenticated where applicable.

Traces to. US-INT-004

FR-INT-005 — Expose a versioned public REST API with idempotency [S]

Description. The system must expose a versioned public REST API for partners, supporting idempotency keys so that a retried request with the same key is processed once.

Rationale. Locked public-API decision (_context.md §4 module H).

Acceptance criteria.

• The API is versioned and documented per the contract in /specs/en/12-api-contract/.
• Requests with an idempotency key are processed once even if retried.
• Responses follow the published contract.
• Authentication is required via API credentials.

Traces to. US-INT-005

FR-INT-006 — Deliver signed outbound webhooks with retries and a circuit breaker [S]

Description. The system must deliver signed outbound webhooks for subscribed events, retrying with exponential backoff up to the configured limit and opening a circuit breaker on repeated failures.

Rationale. Locked webhook decision (_context.md §4 module H).

Acceptance criteria.

• Subscribed events deliver a signed webhook to the registered endpoint.
• On failure, retries follow exponential backoff up to the configured limit.
• Repeated failures open the circuit breaker and pause delivery.
• The payload includes a signature the partner can verify.
• Replay attacks are prevented by timestamp validation.

Traces to. US-INT-005

FR-INT-007 — Apply the adapter pattern to all integrations [M]

Description. Every external integration must be implemented behind a per-system adapter interface, so that the underlying provider can be swapped without changing calling code.

Rationale. Locked adapter-pattern decision (_context.md §4 module H).

Acceptance criteria.

• Each integration (NADRA, SECP, FBR, SRB, PSEB, e-Office) has its own adapter interface.
• Calling code is independent of the underlying provider implementation.
• Adapters can be mocked for testing without external dependencies.

Traces to. US-INT-001, US-INT-002

FR-INT-008 — Apply idempotency, retries, and circuit breakers uniformly [M]

Description. Every integration call must apply idempotency (where the operation is non-read), retries with backoff, and a circuit breaker that opens after configured failures and degrades gracefully.

Rationale. Locked integration resilience decision (_context.md §4 module H).

Acceptance criteria.

• Non-read integration operations are idempotent under a stable operation key.
• Retries follow exponential backoff with jitter, up to a configured limit.
• A circuit breaker opens after configured failures and half-opens for recovery testing.
• Open circuits degrade the calling flow gracefully (pending state) rather than failing the user.

Traces to. US-INT-001, US-INT-002, US-INT-003

FR-INT-009 — Provide an audit log of all integration calls [M]

Description. The system must audit-log every integration call (adapter, direction, request reference, outcome, latency, timestamp) for governance and incident review.

Rationale. Supports governance and the analytics metric family (governance/compliance).

Acceptance criteria.

• Every inbound and outbound integration call is audit-logged.
• The log entry captures adapter, direction, request reference, outcome, latency, and timestamp.
• The log is queryable for incident review and surfaces in governance analytics.

Traces to. US-INT-001, US-ANL-001

ANL — Analytics

Epic E9. Nine metric families, seven role dashboards, drill-down, filters, comparative, scheduled digests, exports, GIS heatmap, anomaly alerts, saved views, embeds, public anonymized dashboard. Traces to US-ANL-001 … US-ANL-006. KPI detail in /specs/en/17-analytics-kpis/.

FR-ANL-001 — Compute the nine metric families [M]

Description. The system must compute the nine metric families: volume/throughput, speed, SLA/escalation, quality/outcome, department/staff performance, AI module metrics, engagement/comms, governance/compliance, and public transparency.

Rationale. Locked nine-metric-family decision (_context.md §4 module I).

Acceptance criteria.

• Each of the nine families is computed on a defined cadence from source data.
• Computed metrics are stored with timestamps and provenance.
• Metrics are surfaced to dashboards per role scope.
• Metric definitions are documented and versioned.

Traces to. US-ANL-001

FR-ANL-002 — Provide role-scoped dashboards for the seven roles [M]

Description. The system must provide a tailored dashboard for each of the seven roles (Super Admin, Dept Admin, DG, Officer, Secretary, Minister/SACM, Company, Public), showing only the metrics relevant to that role and within their scope.

Rationale. Locked seven-dashboard decision (_context.md §4 module I).

Acceptance criteria.

• A dashboard exists for each role.
• Each dashboard shows only metrics within that role's scope (oversight powers respected).
• Officers see personal workload and per-shift KPIs without other officers' individually-identifiable scores.
• Minister/SACM sees province-wide aggregates with oversight scope respected.
• Company role sees its own ticket portfolio.

Traces to. US-ANL-001

FR-ANL-003 — Provide drill-down from summary to detail [M]

Description. The system must let authorized users drill from a summary KPI into the underlying detail (down to ticket list where scope permits).

Rationale. Supports root-cause analysis (US-ANL-002).

Acceptance criteria.

• A summary KPI is clickable to open the underlying detail.
• Drill respects scope (Confidential/VIP hidden from unauthorized users).
• Drill levels are documented per metric.

Traces to. US-ANL-002

FR-ANL-004 — Provide filters by department, section, category, date, district, and severity [M]

Description. The system must let authorized users filter dashboards and charts by department, section, category, date range, district, and severity.

Rationale. Supports investigation and comparative analysis (US-ANL-002).

Acceptance criteria.

• Filters for department, section, category, date range, district, and severity are available.
• Filters apply to all charts and tables on the dashboard.
• Filter selections are reflected in exports.

Traces to. US-ANL-002

FR-ANL-005 — Provide comparative views (period-over-period, department-over-department) [S]

Description. The system must let authorized users compare two periods or two departments side by side.

Rationale. Supports trend and benchmark analysis (US-ANL-002).

Acceptance criteria.

• A period-over-period comparison is available for any metric.
• A department-over-department comparison is available.
• Comparative views are exportable.

Traces to. US-ANL-002

FR-ANL-006 — Provide configurable scheduled digests per role cadence [M]

Description. The system must deliver scheduled analytics digests per role-appropriate cadence (Secretary daily, Minister weekly, Dept Admin daily, DG daily, Officers per-shift), each overridable by the recipient in their preference center, rendered in their preferred language.

Rationale. Locked scheduled-digest decision (_context.md §4 module I).

Acceptance criteria.

• Default digest cadences are pre-configured per role.
• Each recipient can change cadence, channels, and quiet hours.
• Digests render in the recipient's preferred language (RTL for UR/SD).
• Digest content is scoped to the recipient's role.

Traces to. US-ANL-003

FR-ANL-007 — Export dashboards and charts to PDF, Excel, and CSV [M]

Description. The system must let authorized users export any dashboard or chart as PDF, Excel, or CSV, reflecting applied filters and audit-logging the export.

Rationale. Locked export decision (_context.md §4 module I).

Acceptance criteria.

• Export to PDF, Excel, and CSV is available for dashboards and charts.
• The export reflects applied filters, charts, and data tables.
• The export is audit-logged with user, scope, and timestamp.

Traces to. US-ANL-004

FR-ANL-008 — Provide a public transparency dashboard (anonymized) [M]

Description. The system must provide a public, no-login transparency dashboard with aggregate metrics and no PII, applying small-cell suppression.

Rationale. Locked public-dashboard decision (_context.md §4 module I).

Acceptance criteria.

• The dashboard is accessible without login.
• No company name, individual name, ticket ID, or free-text content is exposed.
• Small-cell suppression hides any group below the configured minimum size.
• Figures match source data within the published refresh window.

Traces to. US-ANL-005, US-PUB-008

FR-ANL-009 — Provide a GIS district heatmap [S]

Description. The system must provide a GIS district heatmap of ticket origin and resolution performance.

Rationale. Locked GIS-heatmap decision (_context.md §4 module I).

Acceptance criteria.

• The heatmap renders ticket origin and resolution performance by district.
• District drill-down is available to authorized users.
• Heatmap data is scoped to the user's access.

Traces to. US-ANL-006

FR-ANL-010 — Detect anomalies and predict SLA breaches [S]

Description. The system must detect anomalies in metrics and predict SLA breaches, raising proactive alerts when confidence crosses threshold.

Rationale. Locked anomaly-alert decision (_context.md §4 module I).

Acceptance criteria.

• A predicted breach within 24 hours at confidence above threshold raises an alert.
• Alerts route to the assigned Officer, their DG (watcher), and the Dept Admin digest.
• Anomalies are surfaced on relevant dashboards.

Traces to. US-ANL-006

FR-ANL-011 — Allow saving and sharing named views [S]

Description. The system must let authorized users save a filtered dashboard state as a named view and share it within their scope.

Rationale. Improves repeatability for recurring analyses (US-ANL-002).

Acceptance criteria.

• A user can save filter/chart selections as a named view.
• Named views can be re-applied in one action.
• Views can be shared with other users within scope.
• Shared views respect the recipient's scope on rendering.

Traces to. US-ANL-002

FR-ANL-012 — Provide embeddable dashboard widgets [C]

Description. The system must provide embeddable dashboard widgets (iframe or signed embed) that can be placed in other approved internal tools.

Rationale. Supports embedding in e-Office and partner tools (Could-have).

Acceptance criteria.

• A dashboard or chart can be embedded via signed URL.
• The embed respects the viewer's scope via the signed token.
• Embedded views cannot exceed the embedder's scope.

Traces to. US-ANL-002

FR-ANL-013 — Surface AI cost and usage in analytics [S]

Description. The system must surface AI cost and usage metrics (from FR-AI-014) in analytics dashboards.

Rationale. Supports cost governance of pluggable AI engines.

Acceptance criteria.

• AI cost and usage are aggregated by capability, engine, department.
• Cost-overrun alerts are surfaced.
• Metrics are restricted to authorized roles.

Traces to. US-AI-014, US-ANL-001

FR-ANL-014 — Back dashboards with Metabase and custom charts [M]

Description. The system must back its dashboards with embedded Metabase plus custom ECharts/Recharts visualizations.

Rationale. Locked BI choice (_context.md §3).

Acceptance criteria.

• Metabase is embedded for self-service analytics where appropriate.
• Custom ECharts/Recharts visualizations render role-scoped dashboards.
• Both honor the user's access scope.

Traces to. US-ANL-001

KB — Knowledge Base + SOPs

Epic E10. Articles, downloadable forms, versioned SOPs, AI semantic search, deflection tracking, service catalog, authoring workflow. Traces to US-KB-001 … US-KB-003. Detail in /specs/en/18-knowledge-base-sop/.

FR-KB-001 — Author and publish articles, SOPs, and forms [M]

Description. The system must let KB Authors draft articles, SOPs, and downloadable forms and submit them for editorial review and publication, with versions tracked.

Rationale. Locked KB module behaviour (_context.md §4 module J).

Acceptance criteria.

• Authors can create drafts of articles, SOPs, and forms.
• Submitting moves the item to In Review and notifies a KB Editor.
• On approval, the item is published as a new version; prior versions are archived and accessible.
• Each item carries title, summary, language, and last-updated date.

Traces to. US-KB-002

FR-KB-002 — Version SOPs and articles with changelog [M]

Description. The system must version SOPs and articles on every published change, preserving prior versions and recording a changelog entry.

Rationale. Locked versioned-SOPs decision (_context.md §4 module J).

Acceptance criteria.

• Publishing a change creates a new version.
• Prior versions are archived but accessible.
• A changelog entry is recorded per version.
• The currently-published version is clearly identified.

Traces to. US-KB-002

FR-KB-003 — Provide AI semantic search across KB [M]

Description. The system must provide AI semantic search across articles, SOPs, and forms in EN, UR, and SD, ranked by intent, not just keywords.

Rationale. Locked AI semantic-search decision (_context.md §4 module J).

Acceptance criteria.

• Semantic search returns ranked results matching intent.
• Results cover articles, SOPs, and forms in EN, UR, SD.
• Each result shows title, summary, language, and last-updated date.
• Search uses the pluggable AI engine (FR-AI-012).

Traces to. US-KB-001

FR-KB-004 — Offer downloadable forms without login [M]

Description. The system must offer the latest published version of each downloadable form without requiring authentication.

Rationale. Reduces friction for visitors (US-KB-001).

Acceptance criteria.

• Forms are downloadable from the service catalog and KB.
• The latest published version is delivered.
• No authentication is required.

Traces to. US-KB-001, US-PUB-007

FR-KB-005 — Track "was this helpful" feedback [S]

Description. The system must capture per-article "was this helpful" votes and aggregate them for content review.

Rationale. Locked helpfulness feedback (US-KB-003).

Acceptance criteria.

• A helpful/unhelpful vote control is present on each article.
• Votes are aggregated per article.
• Aggregated votes are visible to KB Authors and Editors.

Traces to. US-KB-003

FR-KB-006 — Track ticket deflection attributed to KB content [S]

Description. The system must track deflection events (a visitor finds the answer in KB and does not file a ticket) and attribute them to the article that deflected.

Rationale. Locked deflection-tracking decision (_context.md §4 module J).

Acceptance criteria.

• A positive helpfulness vote without subsequent ticket filing is recorded as a deflection event.
• The event is attributed to the article surfaced.
• Deflection counts are visible in analytics (engagement metric family).

Traces to. US-KB-003, US-ANL-001

FR-KB-007 — Publish and maintain the service catalog [M]

Description. The system must publish and maintain the service catalog of departments/categories the Portal handles, with links to SOPs, forms, and SLA expectations.

Rationale. Locked service-catalog decision (_context.md §4 module J).

Acceptance criteria.

• The catalog lists every department/category the Portal handles.
• Each entry links to SOPs, forms, and SLA expectations.
• The catalog is filterable by department and category.
• The catalog is multilingual with RTL support.

Traces to. US-PUB-007, US-KB-001

FR-KB-008 — Flag outdated content for review [S]

Description. The system must flag published articles and SOPs whose freshness window has expired for review, notifying their authors.

Rationale. Ensures content currency (US-KB-002).

Acceptance criteria.

• A freshness window is configurable per content type.
• On expiry, the item is flagged Needs Review.
• Authors are notified.
• The flag is visible in the authoring dashboard.

Traces to. US-KB-002

MCI — Multi-channel Intake

Epic E11. Email/SMS/WhatsApp-to-ticket, toll-free IVR/voice, walk-in/offline entry, dedup across channels. Traces to US-MCI-001 … US-MCI-004. Detail in /specs/en/19-multichannel-intake/.

FR-MCI-001 — Create tickets from inbound email [M]

Description. The system must create a ticket from an inbound email to the facilitation desk address from a verified sender, with subject as title, body as description, attachments preserved, and a confirmation reply carrying the tracking ID.

Rationale. Locked email-intake decision (_context.md §4 module K).

Acceptance criteria.

• Inbound email from a verified sender creates a ticket.
• Subject becomes title; body becomes description; attachments are preserved (AV-scanned).
• A confirmation reply is sent carrying the new tracking ID.
• An inbound referencing an existing ticket ID (subject or headers) appends as a comment, not a new ticket.

Traces to. US-MCI-001

FR-MCI-002 — Create and update tickets from WhatsApp and SMS [M]

Description. The system must create and update tickets from inbound WhatsApp and SMS messages to the official number, preserving attachments (AV-scanned) and confirming via the originating channel.

Rationale. Locked WA/SMS-intake decision (_context.md §4 module K).

Acceptance criteria.

• A WhatsApp message (with or without attachment) from a verified contact creates a ticket.
• An SMS reply to a ticket notification appends as a comment.
• Attachments are AV-scanned.
• Confirmation is sent via the originating channel carrying the tracking ID.

Traces to. US-MCI-002

FR-MCI-003 — Provide toll-free IVR/voice intake [S]

Description. The system must provide a toll-free IVR path with a "register a complaint" option that records a voice message, transcribes it (AI with manual fallback), and creates a ticket with the transcript as description and audio attached, confirming via SMS.

Rationale. Locked IVR/voice decision (_context.md §4 module K).

Acceptance criteria.

• The IVR offers a "register a complaint" option.
• A voice recording is captured and stored.
• The recording is transcribed (AI with manual fallback).
• A ticket is created with transcript as description and audio attached.
• The caller receives an SMS with the tracking ID.

Traces to. US-MCI-003

FR-MCI-004 — Provide walk-in/offline intake by staff [M]

Description. The system must let a front-desk Officer enter a walk-in complaint on behalf of a visitor, with offline entry syncing with the original entry timestamp when connectivity returns.

Rationale. Locked walk-in/offline decision (_context.md §4 module K).

Acceptance criteria.

• A front-desk Officer can create a ticket on behalf of a visitor.
• Offline entries are stored locally and sync when connectivity returns.
• The original entry timestamp is preserved on sync.

Traces to. US-MCI-004

FR-MCI-005 — Detect duplicates across channels at intake [M]

Description. At intake from any channel, the system must detect likely duplicates against existing tickets from the same contact, surfacing them for the Officer to merge, link, or proceed as new, with the choice audit-logged.

Rationale. Locked dedup decision (_context.md §4 module K).

Acceptance criteria.

• Intake from any channel runs duplicate detection against existing tickets.
• Likely duplicates are surfaced with similarity scores.
• The Officer can merge, link, or proceed as new.
• The choice is audit-logged.

Traces to. US-MCI-004, US-AI-007

FR-MCI-006 — Capture channel of origin on every ticket [M]

Description. The system must capture and store the channel of origin (web, email, SMS, WhatsApp, IVR, walk-in, API) on every ticket.

Rationale. Supports analytics (volume by channel) and audit.

Acceptance criteria.

• Every ticket stores its channel of origin.
• The channel is visible on the ticket detail.
• The channel feeds analytics dashboards.

Traces to. US-MCI-001, US-ANL-001

FR-MCI-007 — Rate-limit and verify inbound senders [M]

Description. The system must rate-limit inbound from any single source and verify the sender before creating a ticket, holding unverified inbound for review.

Rationale. Trust & safety (locked, _context.md §6).

Acceptance criteria.

• Inbound exceeding per-source thresholds is throttled.
• Unverified senders' inbound is held for review.
• A facilitator is notified of held inbound.

Traces to. US-MCI-001, US-NOT-005

DOC — Document Generation + e-Sign

Epic E12. Trilingual official letters and resolution certificates on letterhead, PKI digital signing, QR verification, date-aware letterheads. Traces to US-DOC-001 … US-DOC-003.

FR-DOC-001 — Generate trilingual official letters on letterhead [M]

Description. The system must generate official letters and resolution certificates on S&ITD or concerned-department letterhead in EN, UR, or SD, with ticket ID, company details, and resolution summary.

Rationale. Locked document-generation decision (_context.md §4 module L).

Acceptance criteria.

• An Officer can generate a letter or resolution certificate from a Resolved ticket.
• The document renders on the appropriate letterhead in EN, UR, or SD.
• The document includes ticket ID, company details, and resolution summary.
• The letter language follows recipient preference unless overridden.
• The document is saved as a versioned attachment on the ticket.

Traces to. US-DOC-001

FR-DOC-002 — Render date-aware letterheads with historical officials [M]

Description. The system must render letterheads using the officials who held office on the document's effective date, even when the document is regenerated later.

Rationale. Locked historical-accuracy decision (_context.md §4 module P, §5).

Acceptance criteria.

• A generated letter uses the official-in-office as of its effective date.
• Regenerating the letter months later retains the historical official in the letterhead.
• Officials are sourced from the OFC module records.

Traces to. US-DOC-001, US-OFC-002

FR-DOC-003 — Apply PKI digital signatures to official documents [M]

Description. The system must apply a PKI digital signature to official documents by an authorized signatory, with certificate metadata, producing an immutable signed document.

Rationale. Locked PKI decision (_context.md §4 module L).

Acceptance criteria.

• An authorized signatory authenticates their PKI credential (with 2FA) and signs.
• A PKI signature is applied with certificate metadata (signer DN, timestamp, validity).
• The signed document is immutable thereafter.
• The signature event is audit-logged.

Traces to. US-DOC-002

FR-DOC-004 — Attach a verifiable QR code to signed documents [M]

Description. The system must attach a QR code to every signed official document that resolves to a public verification page showing issuance date, signing authority, ticket reference, current status, and file-hash match.

Rationale. Locked QR-verification (anti-forgery) decision (_context.md §4 module L).

Acceptance criteria.

• Every signed document carries a QR code.
• Scanning resolves to a public verification page.
• The page shows issuance date, signing authority, ticket reference, current status, and file-hash match.
• A tampered or unknown QR is rejected with a clear "Could not verify" warning.
• Verification attempts are logged.

Traces to. US-DOC-003

FR-DOC-005 — Provide a public document verification portal [M]

Description. The system must provide a public, no-login portal where any recipient or third party can scan or paste a QR code or document reference to verify authenticity.

Rationale. Anti-forgery (US-DOC-003).

Acceptance criteria.

• The portal is accessible without login.
• It accepts QR code or document reference input.
• It returns verification result with the metadata in FR-DOC-004.
• Failed verifications are logged without leaking existence.

Traces to. US-DOC-003

FR-DOC-006 — Persist signed documents as versioned attachments [M]

Description. The system must persist every signed document as a versioned attachment on its ticket, immutable after signing.

Rationale. Evidence integrity (US-DOC-001).

Acceptance criteria.

• A signed document is stored as a ticket attachment.
• The attachment is immutable after signing.
• Regeneration creates a new version, preserving the prior signed version.
• Version history is audit-logged.

Traces to. US-DOC-001

MTG — Hearings + TRI + MoM

Epic E13. Tripartite (Company + S&ITD + Department) hybrid meetings, AI-drafted agendas, MoM upload-first with OCR + AI action extraction, sensitive/VIP approval gate, auto-share, acknowledgment tracking, versioning, recording consent. Traces to US-MTG-001 … US-MTG-006. Detail in /specs/en/21-mom-meetings/.

FR-MTG-001 — Request a TRI meeting from a stalled ticket [M]

Description. The system must let an Officer or DG request a tripartite meeting from a stalled ticket, capturing the three parties (Company rep, concerned Department rep(s), S&ITD facilitator), and blocking confirmation if any required party is missing.

Rationale. Locked TRI decision (_context.md §5).

Acceptance criteria.

• A "Request TRI Meeting" action is available on a ticket.
• The requester adds Company rep, Department rep(s), and S&ITD facilitator.
• Confirmation is blocked if any required party is missing.
• A meeting record is created linked to the ticket.

Traces to. US-MTG-001

FR-MTG-002 — Support physical, virtual, and hybrid modalities [M]

Description. The system must support TRI meetings as physical, virtual, or hybrid, with a configurable video provider (Zoom/Meet/Teams) per meeting.

Rationale. Locked hybrid-modality decision (_context.md §5).

Acceptance criteria.

• A meeting can be marked physical, virtual, or hybrid.
• A hybrid meeting captures both location and virtual link.
• The video provider is selected from Zoom/Meet/Teams per meeting.
• The virtual link is included in invites.

Traces to. US-MTG-001

FR-MTG-003 — Draft an agenda from ticket history and uploads [M]

Description. The system must draft a meeting agenda from ticket history and uploaded evidence, presented to the facilitator for editing before sending invites.

Rationale. Locked AI-agenda decision (_context.md §5).

Acceptance criteria.

• An agenda is auto-drafted when a TRI meeting is created.
• The agenda summarizes ticket history, open questions, and uploaded evidence.
• The facilitator can edit before sending invites.
• The agenda uses the pluggable AI engine.

Traces to. US-MTG-002

FR-MTG-004 — Send calendar invites and reminders [M]

Description. The system must send calendar invites and configurable reminders to all meeting participants.

Rationale. Ensures attendance (US-MTG-002).

Acceptance criteria.

• Calendar invites are sent on confirmation.
• Reminders are sent at configurable intervals before the meeting.
• Invites and reminders carry the meeting details (modality, location, link, agenda).

Traces to. US-MTG-002

FR-MTG-005 — Accept MoM upload-first (PDF/Word/images) [M]

Description. The system must accept a Minutes of Meeting document uploaded in the department's own format (PDF/Word/images), with manual entry and AI transcription available as feature-flagged toggles.

Rationale. Locked MoM upload-first decision (_context.md §5).

Acceptance criteria.

• An Officer can upload an MoM document (PDF/Word/images).
• Manual entry and AI transcription are available as feature-flagged toggles.
• Uploaded MoMs are attached to the meeting record.

Traces to. US-MTG-003

FR-MTG-006 — Run OCR + AI on uploaded MoMs [M]

Description. The system must run OCR (multilingual) and AI on uploaded MoMs to extract a summary and structured action items (owner, due date, text), with low-confidence items flagged.

Rationale. Locked MoM AI decision (_context.md §5).

Acceptance criteria.

• OCR runs on uploaded MoMs (scanned or text).
• A summary is produced.
• Action items with owner, due date, and text are extracted.
• Low-confidence extractions are flagged.
• Uses FR-AI-001 and FR-AI-011.

Traces to. US-MTG-003, US-AI-011

FR-MTG-007 — Convert confirmed action items into ticket sub-tasks [M]

Description. On officer confirmation, each MoM action item must become a sub-task on the originating ticket, assigned to its owner with the stated due date, appearing on the owner's dashboard and SLA tracking.

Rationale. Locked action-item-to-sub-task decision (_context.md §5).

Acceptance criteria.

• Confirmed action items create sub-tasks on the ticket.
• Each sub-task is assigned to the stated owner with the stated due date.
• Sub-tasks appear on the owner's dashboard and SLA tracking.
• Sub-tasks inherit the parent ticket's confidentiality scope.

Traces to. US-MTG-004, US-TKT-014

FR-MTG-008 — Gate sensitive/VIP MoM publishing behind Chair/DG approval [M]

Description. For sensitive or VIP tickets, the system must route the MoM to the Chair/DG for approval before publishing and block auto-share until approved.

Rationale. Locked sensitive-approval decision (_context.md §5).

Acceptance criteria.

• For sensitive/VIP tickets, publishing routes the MoM to Chair/DG.
• Auto-share is blocked until approval.
• Approval (or rejection with reason) is recorded.
• The approval event is audit-logged.

Traces to. US-MTG-005

FR-MTG-009 — Auto-share published MoMs with acknowledgment tracking [M]

Description. On publish (directly or after approval), the system must auto-share the MoM to all participants via email, in-app, SMS, and WhatsApp, tracking each participant's acknowledgment (or non-acknowledgment after the reminder window).

Rationale. Locked auto-share decision (_context.md §5).

Acceptance criteria.

• On publish, the MoM is shared via email, in-app, SMS, and WhatsApp to all participants.
• Each participant's acknowledgment is recorded.
• Non-acknowledgment after the reminder window is recorded.
• The MoM is permanently attached, versioned, and audit-logged.

Traces to. US-MTG-005

FR-MTG-010 — Version and audit MoM documents [M]

Description. The system must version MoM documents on every change, with full audit logging.

Rationale. Evidence integrity (_context.md §5).

Acceptance criteria.

• Each MoM change creates a new version.
• Prior versions are preserved.
• Version changes are audit-logged with actor and timestamp.

Traces to. US-MTG-005

FR-MTG-011 — Capture explicit recording consent [S]

Description. Before recording a virtual meeting, the system must capture explicit consent from all required participants; recording proceeds only after consent.

Rationale. Locked recording-consent decision (_context.md §5).

Acceptance criteria.

• A recording attempt prompts all connected participants for consent.
• Recording proceeds only after all required participants consent.
• Consent records are stored with the meeting.

Traces to. US-MTG-006

FR-MTG-012 — Translate MoM and action items across EN/UR/SD [S]

Description. The system must translate the MoM and action items across EN/UR/SD on request, showing the translation alongside the original.

Rationale. Multilingual participation (US-MTG-006).

Acceptance criteria.

• MoM and action items can be translated across EN/UR/SD.
• The translation is shown alongside the original.
• Uses FR-AI-006.

Traces to. US-MTG-006

SUG — Suggestion & Content Portal

Epic E14. Suggestion box, circulars/announcements, versioned document repository, moderation. Traces to US-SUG-001 … US-SUG-003.

FR-SUG-001 — Accept public suggestions (anonymous or identified) [M]

Description. The system must accept suggestions from a Company Representative or citizen, optionally anonymously, with rate limiting, storing identified submissions with a reference for status tracking.

Rationale. Locked suggestion-box decision (_context.md §4 module N).

Acceptance criteria.

• A visitor can submit a suggestion anonymously.
• A logged-in representative can submit with contact details and receive a reference.
• Submissions are rate-limited to deter spam.
• Anonymous submissions have no identity linkage.

Traces to. US-SUG-001

FR-SUG-002 — Acknowledge identified submissions [M]

Description. The system must send an acknowledgment and reference to an identified submitter on submission, allowing status tracking.

Rationale. Ensures submitters can track (US-SUG-001).

Acceptance criteria.

• An identified submitter receives an acknowledgment with a reference.
• The reference can be used to track suggestion status.
• Status updates are visible to the submitter.

Traces to. US-SUG-001

FR-SUG-003 — Publish targeted circulars and announcements [M]

Description. The system must let a Super Admin or Dept Admin publish circulars and announcements targeted to audiences (all companies, a department, a segment), delivered via in-app banner and chosen channels.

Rationale. Locked broadcast decision (_context.md §4 module N).

Acceptance criteria.

• An Admin composes a circular and selects an audience.
• On publish, the circular is delivered via in-app banner and chosen channels.
• The circular is archived in the content portal.
• Targeting respects audience scope.

Traces to. US-SUG-002

FR-SUG-004 — Maintain a versioned document repository [S]

Description. The system must maintain a versioned document repository where new versions supersede prior ones, preserving history and a changelog.

Rationale. Locked versioned-repository decision (_context.md §4 module N).

Acceptance criteria.

• An editor can upload new versions of repository documents.
• The new version becomes current; the prior is archived but accessible.
• A changelog entry is recorded per version.

Traces to. US-SUG-003

FR-SUG-005 — Apply moderation to user-submitted content [S]

Description. The system must apply a moderation queue to user-submitted content, surfacing only approved content publicly.

Rationale. Trust & safety (_context.md §6).

Acceptance criteria.

• User-submitted content enters a moderation queue.
• Moderators approve, reject, or edit before publication.
• Rejections include a reason visible to the submitter (where identified).
• Moderation actions are audit-logged.

Traces to. US-SUG-003

FR-SUG-006 — Provide an optional public ideas board [C]

Description. The system may provide an optional public ideas board where approved suggestions are visible for up-voting and discussion.

Rationale. Community engagement (Could-have).

Acceptance criteria.

• Approved suggestions may appear on the ideas board.
• Visitors can up-vote and comment per policy.
• The board is gated by a feature flag.

Traces to. US-SUG-001

TRN — Training & Certification

Epic E15. LMS-lite: staff courses + quizzes, exam-gated certification before live ticket handling, re-certification on expiry. Traces to US-TRN-001 … US-TRN-003. Detail in /specs/en/20-training-certification/.

FR-TRN-001 — Provide staff training courses with quizzes [M]

Description. The system must provide training courses that staff can enroll in, consume, and complete by passing the course quiz at or above the pass mark.

Rationale. Locked LMS-lite decision (_context.md §4 module O).

Acceptance criteria.

• An Officer can enroll in a course.
• Course content is consumable in the portal.
• A quiz is associated with each course.
• Passing the quiz at or above the pass mark records completion with score and timestamp.

Traces to. US-TRN-001

FR-TRN-002 — Record completion and score on learner profile [M]

Description. The system must record course completion and quiz score against the learner's profile.

Rationale. Supports exam-gate enforcement (FR-ORG-010).

Acceptance criteria.

• Completion is recorded on the learner's profile.
• Score and timestamp are stored.
• The profile is visible to the learner and their supervisor.

Traces to. US-TRN-001

FR-TRN-003 — Provide exam-gated certification [M]

Description. The system must require an Officer to pass the certification exam before being assignable any live ticket.

Rationale. Locked exam-gate decision (_context.md §4 module O, §5).

Acceptance criteria.

• An uncertified Officer cannot receive live ticket assignments (auto or manual).
• A blocking message explains the certification requirement.
• Passing the certification exam unblocks assignment.
• The gate status is visible to the supervisor.

Traces to. US-TRN-002, US-ORG-010

FR-TRN-004 — Provide invigilation/anti-cheating on certification exams [S]

Description. The system must apply invigilation/anti-cheating measures (e.g., time limits, randomized question banks, tab-switch detection) to certification exams.

Rationale. Certification integrity.

Acceptance criteria.

• Certification exams enforce a time limit.
• Question banks are randomized per attempt.
• Tab-switch or window-blur events are logged.
• Suspicious patterns are flagged for review.

Traces to. US-TRN-002

FR-TRN-005 — Enforce certification expiry and re-certification [S]

Description. The system must expire certifications on a defined cadence, send advance warnings, and move uncertified-by-expiry staff to read-only ticket access until re-certified.

Rationale. Locked expiry decision (_context.md §4 module O).

Acceptance criteria.

• Certifications have a defined expiry cadence.
• Advance warnings are sent to the Officer and Dept Admin (default 14 days before).
• On expiry without re-certification, the Officer moves to read-only ticket access.
• Re-certification by passing the exam restores eligibility.

Traces to. US-TRN-003

FR-TRN-006 — Provide course and exam authoring for admins [S]

Description. The system must let authorized admins author courses and exams (content, questions, pass marks) without code changes.

Rationale. Maintains training currency.

Acceptance criteria.

• An admin can create/edit courses and exams.
• Pass marks and time limits are configurable per exam.
• Authoring is audit-logged.

Traces to. US-TRN-001

OFC — Brand & Officials CMS

Epic E16. Dynamic Minister/Secretary/DG records (name, photo, effective dates, message), propagation to site/letters/dashboards, date-aware historical accuracy, media library, brand/theme. Traces to US-OFC-001 … US-OFC-004.

FR-OFC-001 — Maintain dynamic officials records [M]

Description. The system must maintain records for the Minister, Secretary, and DG including name, photo, effective dates, and message, with full CRUD by authorized Brand Editors.

Rationale. Locked officials-CMS decision (_context.md §4 module P).

Acceptance criteria.

• Brand Editors can create, read, update, and (soft-)delete official records.
• Each record carries name, photo, effective-from/effective-to dates, and message.
• Records are multilingual where the message is concerned.

Traces to. US-OFC-001

FR-OFC-002 — Activate officials by effective date [M]

Description. The system must activate a new official automatically on their effective date, replacing the prior official as current and moving the prior to historical records.

Rationale. Locked effective-date decision (_context.md §4 module P).

Acceptance criteria.

• A new record with an effective date becomes current on that date.
• The prior official moves to historical records.
• The change propagates to site, letters, and dashboards.

Traces to. US-OFC-001

FR-OFC-003 — Propagate officials atomically across surfaces [M]

Description. On approval, official-record changes must propagate to the public site, letters, and dashboards in a single transaction, audit-logged.

Rationale. Locked propagation decision (_context.md §4 module P).

Acceptance criteria.

• An approved change propagates to site, letters, and dashboards atomically.
• Propagation is audit-logged.
• A failed propagation rolls back atomically.

Traces to. US-OFC-004

FR-OFC-004 — Provide date-aware letterheads for historical accuracy [M]

Description. Letters and certificates must display the officials who held office on the document's effective date, even when regenerated later.

Rationale. Locked historical-accuracy decision (_context.md §5).

Acceptance criteria.

• A letter uses the official-in-office as of its effective date.
• Regenerating retains the historical official in the letterhead.
• The official is sourced from OFC records.

Traces to. US-OFC-002, US-DOC-002

FR-OFC-005 — Apply an approval workflow to official-record changes [M]

Description. Changes to senior-official records must go through a Super Admin approval workflow before propagating.

Rationale. Locked approval-workflow decision (_context.md §4 module P).

Acceptance criteria.

• A Brand Editor's change is queued for Super Admin approval.
• The change does not propagate until approved.
• Approval (or rejection with reason) is recorded.

Traces to. US-OFC-004

FR-OFC-006 — Provide a central media library [S]

Description. The system must provide a central media library for official photos, logos, and motifs, reusable across surfaces.

Rationale. Locked media-library decision (_context.md §4 module P).

Acceptance criteria.

• Brand Editors can upload, tag, and manage media assets.
• Assets are reusable across site, letters, and dashboards.
• Asset changes propagate to surfaces using them.

Traces to. US-OFC-003

FR-OFC-007 — Provide configurable brand/theme [S]

Description. The system must provide configurable brand/theme (colors, logo lockup, Ajrak motifs) that propagates across surfaces on publish, with prior themes versioned.

Rationale. Locked brand decision (_context.md §7).

Acceptance criteria.

• Brand Editors can configure colors, logo lockup, and Ajrak motifs.
• On approval, the theme applies across site and staff portal on next render.
• Prior theme is versioned.
• Changes are audit-logged.

Traces to. US-OFC-003

FFG — Feature Flags

Epic E17. Every capability toggleable by Super Admin per department/environment, with safe defaults and immutable audit. Traces to US-FFG-001 … US-FFG-003.

FR-FFG-001 — Provide per-department and per-environment feature flag CRUD [M]

Description. The system must let a Super Admin create, read, update, and delete feature flags scoped per department and per environment (dev/staging/prod), with changes taking effect without a deploy.

Rationale. Locked feature-flag decision (_context.md §4 module Q).

Acceptance criteria.

• A Super Admin can manage feature flags from a console.
• Flags are scoped per department and per environment.
• A flag change takes effect immediately without a deploy.
• Affected users see a controlled state when a flag changes (e.g., "temporarily unavailable").

Traces to. US-FFG-001

FR-FFG-002 — Gate every product capability behind a flag [M]

Description. Every product capability (module, sub-feature) must be gated by a feature flag.

Rationale. Locked all-capabilities-toggleable decision (_context.md §4 module Q).

Acceptance criteria.

• Every capability has an associated flag.
• Disabling a flag hides or degrades the capability gracefully.
• The flag registry is complete (no ungated capability in production).

Traces to. US-FFG-001

FR-FFG-003 — Use safe fail-open/fail-closed defaults [M]

Description. Every gated code path must fall back to a configured fail-safe default if the flag service is unreachable (off for non-essential features, on for critical paths), and log the event.

Rationale. Locked safe-default decision (_context.md §4 module Q).

Acceptance criteria.

• Flag service unreachability yields the configured fail-safe default.
• Non-essential features fail closed (off).
• Critical paths fail open (on).
• The event is logged.

Traces to. US-FFG-002

FR-FFG-004 — Audit-log every flag change immutably [M]

Description. Every flag change must be recorded immutably with actor, flag key, previous value, new value, scope (department/environment), and timestamp, surfaced in governance analytics.

Rationale. Locked audit decision (_context.md §4 module Q).

Acceptance criteria.

• Every flag change writes an immutable audit entry.
• The entry captures actor, flag key, previous/new value, scope, timestamp.
• The entry appears in governance/compliance analytics.
• The entry cannot be edited or deleted.

Traces to. US-FFG-003

FR-FFG-005 — Provide pre-configured default flag states per environment [M]

Description. The system must ship pre-configured default flag states per environment, applied on first install and on environment reset.

Rationale. Predictable environment behaviour.

Acceptance criteria.

• Each environment (dev/staging/prod) has pre-configured default flag states.
• Defaults are applied on first install and on environment reset.
• Defaults are documented and versioned.

Traces to. US-FFG-001

FR-FFG-006 — Provide a flag evaluation API for code paths [M]

Description. The system must provide a flag evaluation API that code paths consult, returning the effective value for the given context (department, environment, user attributes).

Rationale. Standardized flag evaluation.

Acceptance criteria.

• A flag evaluation API accepts flag key and context.
• It returns the effective value (with reason and fail-safe marker).
• The API is cached locally for resilience.

Traces to. US-FFG-002

XCU — Cross-cutting Requirements

Capabilities that span every module: audit logging, full-text search, localization, accessibility, role-scoped landing/dashboards.

FR-XCU-001 — Audit-log every state-changing action immutably [M]

Description. The system must audit-log every state-changing action across all modules (ticket, account, RBAC, file, flag, content), capturing actor, action, entity, before/after, timestamp, immutably and queryable.

Rationale. Governance, compliance, and incident review (_context.md §6).

Acceptance criteria.

• Every state-changing action writes an immutable audit entry.
• The entry captures actor, action, entity, before/after, timestamp.
• The audit log is queryable by authorized roles.
• Entries cannot be edited or deleted.
• Audit data feeds governance/compliance analytics.

Traces to. US-ANL-001

FR-XCU-002 — Provide multilingual full-text search across all content [M]

Description. The system must provide full-text search (Meilisearch) across all content types (tickets, KB, messages, suggestions, documents via OCR text), correctly matching EN, UR, and SD keywords.

Rationale. Locked search choice (_context.md §3); searchability is foundational.

Acceptance criteria.

• Search indexes all content types including OCR-extracted text.
• Search returns results ranked by relevance with snippets and source links.
• UR and SD keywords match correctly.
• Search respects access scope (Confidential/VIP hidden from unauthorized users).
• Search is available across staff and (where applicable) public surfaces.

Traces to. US-COM-007, US-KB-003

FR-XCU-003 — Localize all user-facing content to EN, UR, SD [M]

Description. All user-facing content (UI strings, notifications, documents, KB, dashboards) must be localizable to EN, UR, and SD with RTL rendering, driven by _glossary.md.

Rationale. Locked localization decision (_context.md §2).

Acceptance criteria.

• All user-facing strings are externalized and translated to EN, UR, SD.
• UR and SD render RTL.
• Domain terms use approved glossary translations.
• Untranslated strings are flagged in the localization pipeline.

Traces to. US-PUB-001

FR-XCU-004 — Meet WCAG 2.1 AA across the entire portal [M]

Description. All portal surfaces (public and staff) must meet WCAG 2.1 AA in EN, UR, and SD.

Rationale. Locked accessibility decision (_context.md §2).

Acceptance criteria.

• Automated and manual WCAG 2.1 AA audits pass across the portal.
• Keyboard navigation, screen-reader semantics, and contrast meet AA.
• RTL accessibility is validated for UR/SD.
• Forms expose labels, errors, and instructions programmatically.

Traces to. US-PUB-009

FR-XCU-005 — Provide role-scoped landing pages and dashboards [M]

Description. On sign-in, each user must land on a page tailored to their role and scope, surfacing relevant actions and metrics.

Rationale. Role-aware UX (_context.md §4 module I).

Acceptance criteria.

• Each role has a tailored landing page.
• The landing page surfaces role-relevant actions and metrics within scope.
• The page respects access scope (Confidential/VIP hidden).

Traces to. US-ANL-002

FR-XCU-006 — Display dual Gregorian and Hijri dates [M]

Description. The system must display dates in both Gregorian and Hijri calendars across the UI per government convention.

Rationale. Locked dual-calendar decision (_context.md §2).

Acceptance criteria.

• Date displays render both Gregorian and Hijri.
• Hijri conversion is accurate per the Umm al-Qura convention.
• Date pickers offer both calendars where applicable.

Traces to. US-PUB-001

4. Traceability Summary

The table below summarizes FR counts per module and representative User Story IDs. Full per-requirement traceability lives inline in each FR's Traces to line and in /specs/en/13-test-strategy/.

4.1 Coverage checks

• Every Epic E1–E17 has at least one FR per User Story.
• Every locked decision in _context.md §5 (escalation ladder, proof-of-resolution gate, registration, MoM, TRI) is realized by at least one FR.
• Every one of the eleven AI capabilities has a dedicated FR (FR-AI-001 through FR-AI-011), plus the pluggable-engine abstraction (FR-AI-012), per-feature flags (FR-AI-013), and cost logging (FR-AI-014).
• Every external integration in _context.md §4 module H has at least one FR, with adapter-pattern, idempotency, retries, and circuit breakers applied uniformly (FR-INT-007, FR-INT-008).
• All cross-cutting concerns (audit, search, localization, accessibility, role-scoped landing, dual calendar) are covered in XCU.

4.2 Downstream references

• Test Cases — derived from each FR's Acceptance criteria; live in /specs/en/13-test-strategy/ as TC-<EPIC>-<nnn>-<nn>.
• Data model — entities implied by these FRs are specified in /specs/en/05-data-model/.
• Workflow — ticket state transitions implied by FR-TKT-* are specified in /specs/en/06-ticket-workflow/.
• RBAC — permission templates and overrides implied by FR-ORG-* are specified in /specs/en/04-roles-permissions/.
• API contract — REST/webhook endpoints implied by FR-INT-* are specified in /specs/en/12-api-contract/.