Product Requirements Document (PRD)

Reading order for a single requirement:

Epic → User Story (US) → Acceptance Criteria (Gherkin Scenarios) → Test Cases (TC)

Functional requirement IDs (FR-<MOD>-<nnn>) are referenced inline inside User Stories where they aid traceability to the functional requirements catalogue in /specs/en/02-functional-reqs/. Non-functional requirements (NFR-<CAT>-<nnn>) live in /specs/en/03-non-functional-reqs/ and are not duplicated here.

1.2 MoSCoW tags

Every User Story is tagged with exactly one MoSCoW priority (per _conventions.md §5):

• [M] Must — V1 launch blocker.
• [S] Should — V1, delivered soon after launch.
• [C] Could — Nice-to-have in V1 if time permits.
• [W] Won't — Explicitly deferred to a later phase.

All features described in this PRD are in scope for V1; the MoSCoW tag controls sequencing, not inclusion. See §4 for the distribution.

1.3 Language & behavior conventions

• Stories are written behavior-first and UI-agnostic. They describe what the system must do, not how the screen looks.
• Gherkin scenarios use language-neutral nouns ("the representative", "the staff member", "the system"). Screens, buttons, and visual design live in /specs/en/10-ux-sitemap-flows/.
• All flows apply across English, Urdu, and Sindhi, with RTL rendering for Urdu and Sindhi, unless explicitly stated otherwise.
• Ticket identifiers follow the locked format SITP-YYYY-<DEPT>-<NNNNNN> (e.g., SITP-2026-LBR-000123).

2. Module / Epic Map

All 17 epics of the SITP V1 are listed below. Part 1 of this PRD covers E1–E8; Part 2 (_part2_en.md) covers E9–E17 and the traceability matrix.

3. MoSCoW Distribution Summary

All features in this PRD are V1 scope. The MoSCoW tag denotes sequencing and launch-blocking priority, not inclusion.

• [M] Must stories are launch blockers — the Portal cannot go live to the IT industry without them. They cluster in E1–E4 (registration, ticketing, files, core AI/OCR) and the foundational tiers of E6–E8.
• [S] Should stories are V1 but delivered immediately after the Must set is in production (typically within the first stabilization release). They include advanced ticket operations (merge/split, watchers), the upper tiers of internal comms, two-way inbound messaging, AI draft replies, and most external integrations (NITB e-Office, public API).
• [C] Could stories are valuable but non-essential for V1; they will be picked up if capacity allows (e.g., Tier 3 channel-based chat).
• [W] Won't stories are explicitly out of phase; there are none declared Must-defer in E1–E8.

This sequencing aligns with the phased roadmap in /specs/en/14-roadmap-release/: Phase 1 MVP = Must; Phase 2 = Should; Phase 3+ = Could and the E9–E17 modules in Part 2.

4. Epics E1–E8

Epic E1 — Public Site (PUB)

Goal: Provide an unauthenticated, multilingual (EN/UR/SD, RTL-ready) front door to the Portal where IT companies, investors, and the public can learn about the platform, browse the service catalog and FAQs, get AI-assisted guidance and filing help, and view a public transparency snapshot — all without an account, and fully indexed for search engines in every supported language.

US-PUB-001 — Browse the multilingual information site [M]

As a member of the public (IT company, investor, or citizen) I want to read all public pages in English, Urdu, or Sindhi So that I can understand the Portal's purpose, scope, and how to use it in my preferred language.

Satisfies FR-PUB-001, FR-PUB-002.

Acceptance Criteria (Gherkin)

Scenario: Visitor switches interface language
  Given a visitor opens any public page
  When they select "اردو" (Urdu) from the language switcher
  Then all page text is rendered in Urdu
  And the page layout switches to right-to-left (RTL)
  And the URL or locale prefix reflects the selected language

Scenario Outline: Each supported language renders for every public page
  Given the public site is available in languages <Lang>
  When a visitor opens the home, about, services, FAQ, help, or contact page
  Then the page renders fully in <Lang> with no fallback strings in English
  And the page is WCAG 2.1 AA compliant for that language

  Examples:
    | Lang   |
    | EN     |
    | UR     |
    | SD     |

US-PUB-002 — Search the FAQ and help center [M]

As a visitor I want to search a curated FAQ and help center by keyword So that I can find answers to common questions without filing a ticket.

Satisfies FR-PUB-003.

Acceptance Criteria (Gherkin)

Scenario: Keyword search returns relevant FAQ articles
  Given the FAQ and help center contain indexed articles in EN, UR, and SD
  When a visitor searches for "how to register my company"
  Then the system returns articles whose title or body match the query in the visitor's active language
  And results are ranked by relevance
  And each result links to the full article

Scenario: No results offers escalation path
  Given a visitor's search returns zero results
  Then the system offers a link to the AI chatbot and a "contact us" option

US-PUB-003 — Chat with the AI assistant for guided filing [M]

As a visitor I want to ask an AI assistant questions and get help filing a ticket So that I can resolve simple issues immediately or be guided into a correct ticket submission.

Satisfies FR-AI-008, FR-PUB-004. Handoff rules align with US-AI-006.

Acceptance Criteria (Gherkin)

Scenario: AI assistant answers from approved knowledge base
  Given the AI assistant is enabled and a visitor opens the chat widget
  When the visitor asks a question covered by the knowledge base
  Then the assistant responds in the visitor's active language
  And the response cites the source article or FAQ entry

Scenario: Assistant escalates to human when uncertain
  Given the assistant cannot answer with sufficient confidence
  Then it offers to hand off to a live facilitator
  And on acceptance, a chat or ticket session is created and routed to the next available facilitator
  And the conversation transcript is preserved and attached

Scenario: Assistant can pre-fill a ticket draft
  Given a visitor confirms they want to file a ticket
  When the assistant has gathered the necessary details
  Then a ticket draft is created with category, title, and description pre-populated
  And the visitor is taken to the filing flow to review and submit

US-PUB-004 — Multilingual SEO with hreflang [S]

As a search engine I want each public page to declare language and regional alternates via hreflang and a complete sitemap So that the correct language version is served to users in Pakistan and abroad.

Satisfies FR-PUB-005.

Acceptance Criteria (Gherkin)

Scenario: Each public page emits correct hreflang alternates
  Given a public page exists in EN, UR, and SD
  When a crawler fetches any language version
  Then the HTML head contains hreflang link tags for EN, UR, and SD plus an x-default
  And a sitemap.xml entry exists for each language version

Scenario: Structured data is present
  Given a service catalog entry or FAQ article is published
  Then the page includes appropriate structured-data markup
  And the markup validates against the chosen schema

US-PUB-005 — Onboarding wizard for new entities [S]

As a prospective company representative I want a guided onboarding wizard that asks my entity type and recommends next steps So that I know exactly how to register, what documents to prepare, and which services apply to me.

Satisfies FR-PUB-006.

Acceptance Criteria (Gherkin)

Scenario: Wizard tailors guidance by entity type
  Given a visitor starts the onboarding wizard
  When they indicate their entity type (SECP company, sole proprietor/partnership, freelancer, foreign branch, or early startup)
  Then the wizard presents the registration requirements specific to that entity type
  And offers a checklist of documents and a direct link to start registration

Scenario: Wizard saves progress anonymously and on sign-up
  Given a visitor has completed part of the wizard
  When they register an account
  Then their wizard responses are attached to the new account
  And they resume from where they left off

US-PUB-006 — Browse the service catalog and view the public transparency snapshot [M]

As a visitor I want to browse a service catalog of departments/categories the Portal handles and see aggregate transparency statistics So that I understand what I can raise with the Portal and what the Portal's track record looks like.

Satisfies FR-PUB-007, FR-ANL-009 (public dashboard slice).

Acceptance Criteria (Gherkin)

Scenario: Visitor browses the service catalog
  Given the service catalog is published
  When a visitor opens the services page
  Then they see a list of departments and service categories the Portal accepts
  And each entry links to its SOPs, forms, and SLA expectations
  And the page is filterable by department and category

Scenario: Public transparency dashboard renders aggregate, non-PII metrics
  Given the public transparency dashboard is enabled
  When any visitor opens it without logging in
  Then they see aggregate metrics such as total tickets filed, percent resolved within SLA, average resolution time, and volume by department
  And no personally identifiable information or ticket-level detail is exposed
  And the figures match the source data within the dashboard's published refresh window

Scenario: Transparency dashboard is multilingual and accessible
  Given the dashboard renders in EN
  When the visitor switches to UR or SD
  Then all labels, legend, and tooltips render in the selected language
  And the dashboard meets WCAG 2.1 AA

Epic E2 — Ticketing Core (TKT)

Goal: Provide a complete ticket lifecycle for IT-industry problems raised against any Government of Sindh department — from intelligent intake (dynamic conditional forms, AI routing suggestion, smart deflection), through tracking and collaboration (drafts, sub-tasks, merge/split, link/relate, watchers/CC, bulk actions), to a strict proof-of-resolution gate that mandates evidence before closure, CSAT collection, and appeal/reopen. All governed by the SLA and escalation ladder in _context.md §5 and the workflow in /specs/en/06-ticket-workflow/.

US-TKT-001 — File a ticket via a dynamic, conditional form [M]

As a Company Representative I want to submit a ticket whose fields adapt to the selected department and category So that I provide exactly the information the concerned department needs, no more and no less.

Satisfies FR-TKT-001, FR-TKT-002, FR-TKT-004.

Acceptance Criteria (Gherkin)

Scenario: Successful submission generates a meaningful tracking ID
  Given a verified company representative is signed in
  When they complete the dynamic form with title, description, department, category, and any required fields for that category
  Then a ticket is created with status "New"
  And a tracking ID matching "SITP-YYYY-<DEPT>-<NNNNNN>" is generated
  And a confirmation notification is sent in the representative's preferred language

Scenario Outline: Conditional fields appear and validate by category
  Given a representative selects department <Dept> and category <Cat>
  When the form renders the category-specific field set
  Then the fields required by <Cat> are displayed and mandatory
  And fields not relevant to <Cat> are hidden
  And submission is blocked until all required fields are valid

  Examples:
    | Dept | Cat                       |
    | LBR  | EOBI registration         |
    | SRB  | Sales tax on services     |
    | IND  | Industrial estate allotment |

US-TKT-002 — AI auto-route suggestion on submission [M]

As a triage officer I want the system to suggest a department, section, and urgency for each new ticket using AI So that I can confirm or correct routing quickly instead of reading every ticket from scratch.

Satisfies FR-AI-002, FR-AI-003, FR-TKT-005.

Acceptance Criteria (Gherkin)

Scenario: AI suggests routing and urgency at intake
  Given a new ticket has been submitted
  When the AI routing service processes it
  Then a suggested department, section, and urgency level are attached to the ticket for officer review
  And the suggestion includes a confidence score
  And the officer can accept, modify, or reject the suggestion

Scenario: Officer override is logged
  Given the AI suggested department X
  When the triage officer changes it to department Y
  Then the ticket is routed to department Y
  And the override, the original suggestion, and the officer's identity are recorded in the audit log

US-TKT-003 — Track ticket status by tracking ID without login [M]

As a anyone who has a tracking ID I want to look up the status of a ticket without signing in So that I can monitor progress from any device, including when I am not at my company account.

Satisfies FR-TKT-007.

Acceptance Criteria (Gherkin)

Scenario: Anonymous status lookup by tracking ID
  Given a person holds a valid tracking ID
  When they enter it on the public tracking page
  Then the system shows the ticket's current status, the department handling it, the last public status-change date, and the SLA clock state
  And no internal notes, attachments, or staff identifiers are exposed

Scenario: Invalid tracking ID is rejected safely
  Given a person enters an unknown or malformed tracking ID
  Then the system returns a generic "not found" message
  And no information is leaked about whether the ID exists
  And repeated invalid attempts are rate-limited

US-TKT-004 — Save a draft and resume later with smart filing assistance [M]

As a Company Representative I want to save a partially completed ticket as a draft and get AI suggestions about similar resolved tickets before submitting So that I do not lose progress and avoid filing duplicates.

Satisfies FR-TKT-003, FR-AI-007.

Acceptance Criteria (Gherkin)

Scenario: Draft is preserved across sessions
  Given a representative has started but not submitted a ticket
  When they save the draft and return later (possibly from another device)
  Then their draft is listed under their drafts
  And resuming it restores all previously entered fields and attachments

Scenario: Smart filing assistant deflects duplicates
  Given a representative is composing a draft
  When at least a title and description are present
  Then the assistant surfaces similar resolved or open tickets
  And if a representative accepts a similar resolved ticket as their answer, the draft can be discarded with one action
  And the deflection event is recorded for analytics

US-TKT-005 — Sub-tasks, merge/split, link/relate, watchers/CC, and bulk actions [S]

As a staff member or facilitator I want to decompose, combine, relate, watch, and act on multiple tickets So that I can manage complex, multi-faceted issues efficiently.

Satisfies FR-TKT-008, FR-TKT-009, FR-TKT-010, FR-TKT-011, FR-TKT-012.

Acceptance Criteria (Gherkin)

Scenario: A ticket is split into sub-tasks
  Given a parent ticket with multiple distinct issues
  When a facilitator creates sub-tasks
  Then each sub-task has its own assignee, status, and SLA
  And the parent ticket cannot be closed until all sub-tasks are resolved or explicitly waived
  And the parent ticket displays the roll-up status of its sub-tasks

Scenario: Duplicate tickets are merged
  Given two or more tickets describe the same underlying issue from the same company
  When a facilitator merges them into a primary ticket
  Then the secondary tickets are marked "Merged into <primary ID>" and locked
  And all attachments, comments, and watchers are consolidated onto the primary
  And the merge action and actor are audit-logged

Scenario: Bulk action applies to a filtered selection
  Given a facilitator has filtered a list of tickets
  When they select multiple tickets and choose a bulk action
  Then the action is applied to all selected tickets
  And each affected ticket records the action and actor in its history

US-TKT-006 — Resolve with mandatory proof, auto-close, reopen, appeal, and CSAT [M]

As a concerned department staff member I want to resolve a ticket only after attaching evidence and a resolution note, and have the system auto-close it after the CSAT window unless the company reopens or appeals So that closures are evidence-backed and the company retains a meaningful voice.

Satisfies FR-TKT-013, FR-TKT-014, FR-TKT-015, FR-TKT-016. Aligns with the Resolution Proof Gate in _context.md §5.

Acceptance Criteria (Gherkin)

Scenario: Resolution requires evidence and a note
  Given a staff member attempts to move a ticket to "Resolved"
  When no evidence attachment and resolution note are present
  Then the transition is blocked
  And the system states which required items are missing

Scenario: Auto-close after CSAT window
  Given a ticket is in "Resolved" state with all required evidence
  When the CSAT window elapses without company action
  Then the ticket automatically transitions to "Closed"
  And the closure event, timestamp, and trigger are recorded

Scenario: Company rejects resolution
  Given a ticket is "Resolved"
  When the company representative rejects the resolution within the CSAT window
  Then the ticket reopens to its prior working state
  And the SLA clock resumes according to policy
  And the assigned staff and watchers are notified

Scenario: Company appeals a closed ticket
  Given a ticket is "Closed"
  When the company initiates an appeal
  Then an appeal record is created and routed to the next escalation tier
  And the original ticket is linked to the appeal and marked "Under Appeal"

Epic E3 — Organization & RBAC (ORG)

Goal: Model the real-world structure of both sides of the Portal — companies (with multiple authorized representatives and granular per-permission overrides) and government departments (nested dept → section → staff, with DG and Secretary oversight) — while enforcing the locked decisions in _context.md §5: five entity types with a conditional registration form, file-first/verify-in-parallel with a Provisional badge, exactly one Primary Authorized Rep per company, automated lifecycle events, step-up authentication, confidential/VIP ticket access control, and an exam-gate before staff handle live tickets. RBAC detail lives in /specs/en/04-roles-permissions/.

US-ORG-001 — Register as one of five entity types via a conditional form [M]

As a prospective IT company I want to register through a form that adapts to my entity type So that I provide only the information and documents relevant to my structure.

Satisfies FR-ORG-001.

Acceptance Criteria (Gherkin)

Scenario Outline: Conditional registration per entity type
  Given a prospective registrant selects entity type <Type>
  When the registration form renders
  Then only the fields and document requirements applicable to <Type> are shown and validated
  And the form collects the Primary Authorized Rep as a mandatory role

  Examples:
    | Type                              |
    | SECP company                      |
    | Sole proprietor / partnership     |
    | Freelancer / individual           |
    | Foreign branch                    |
    | Early startup (provisional)       |

US-ORG-002 — File-first with Provisional badge, verify-in-parallel [M]

As a newly registered company I want an instant Provisional account that lets me file tickets immediately So that I am not blocked while background verifications complete in parallel.

Satisfies FR-ORG-002, FR-ORG-003. Integrates with Epic E8 (SECP/FBR/SRB/PSEB/NADRA lookups).

Acceptance Criteria (Gherkin)

Scenario: Provisional account is granted on registration
  Given a registrant submits a complete registration
  When the submission is accepted
  Then a Provisional account is created with a "Provisional" badge
  And the account can file tickets immediately
  And background verifications (SECP/FBR/SRB/PSEB/NADRA + domain email) are queued in parallel

Scenario Outline: Verification outcome transitions the badge
  Given a Provisional account is undergoing verification
  When verifications <Result>
  Then the badge transitions to <Badge>
  And the company is notified with the reason

  Examples:
    | Result                       | Badge      |
    | all checks pass              | Verified   |
    | any check fails              | On Hold    |

Scenario: Failed verification offers an appeal
  Given a company's verification has failed
  Then the company can submit an appeal with supporting evidence
  And the appeal is routed to S&ITD for adjudication

US-ORG-003 — Manage multiple authorized representatives with exactly one Primary [M]

As a company administrator I want to add multiple authorized representatives and designate exactly one as Primary So that the right people can act for the company and there is always a single accountable contact.

Satisfies FR-ORG-004.

Acceptance Criteria (Gherkin)

Scenario: Add a representative with a role template
  Given a company administrator is managing representatives
  When they add a new representative with CNIC and domain email
  Then the representative is invited and assigned a role template (Admin, Filer, Viewer, or Notify)
  And the invitee must accept before gaining access

Scenario: Exactly one Primary Authorized Rep at all times
  Given a company has a current Primary Authorized Rep
  When the administrator transfers the Primary role to another representative
  Then the prior Primary becomes a regular representative
  And the new representative becomes the sole Primary
  And the change is audit-logged

US-ORG-004 — Role templates with granular per-permission overrides [M]

As a company administrator or department admin I want to assign role templates and then override individual permissions So that access matches each user's actual responsibilities.

Satisfies FR-ORG-005. Detail in /specs/en/04-roles-permissions/.

Acceptance Criteria (Gherkin)

Scenario: Apply a role template
  Given an administrator assigns a role template to a user
  When the assignment is saved
  Then the user receives every permission in the template

Scenario: Granular override narrows or extends a template
  Given a user holds a role template
  When the administrator toggles an individual permission
  Then the user's effective permission set is the template adjusted by the override
  And the override and actor are audit-logged
  And a denied permission is enforced even if the template would grant it

US-ORG-005 — Nested departments with DG/Secretary oversight [M]

As a Portal administrator I want to model departments as Department → Section → Staff and assign DG and Secretary oversight roles So that tickets route to the correct section while senior leadership retains visibility.

Satisfies FR-ORG-006, FR-ORG-007. Feeds the escalation ladder in _context.md §5.

Acceptance Criteria (Gherkin)

Scenario: Administrator creates a department and nested sections
  Given a Portal administrator is signed in
  When they create a department and one or more sections under it
  Then tickets can be routed to the department or to a specific section
  And the department hierarchy is reflected in routing and reporting

Scenario: Oversight roles receive notifications per escalation tier
  Given a department has an assigned DG and Secretary
  When a ticket in that department breaches the relevant SLA threshold
  Then the DG or Secretary is added as a watcher and notified according to the escalation ladder
  And their oversight power (notify-only vs action) is enforced per the department's configuration

US-ORG-006 — Automated account lifecycle on transfer, rep-change, or strike-off [M]

As a system I want to automatically deactivate or re-verify accounts when material events occur So that access stays accurate to the real-world status of the company and its representatives.

Satisfies FR-ORG-008.

Acceptance Criteria (Gherkin)

Scenario Outline: Lifecycle event triggers an account action
  Given a company account is active
  When event <Event> is detected or reported
  Then the system performs <Action>
  And open tickets are reassigned or paused per policy
  And the action is recorded in the audit log

  Examples:
    | Event                                | Action                                  |
    | Primary rep transferred              | Deactivate previous rep, notify company |
    | Authorized representative changed    | Re-verify the new rep                   |
    | Company struck off by SECP           | Deactivate company account              |

US-ORG-007 — Step-up auth, confidential/VIP ABAC, and exam-gate for staff [S]

As a security officer I want sensitive actions to require step-up authentication, confidential/VIP tickets to enforce attribute-based access, and staff to pass a certification exam before handling live tickets So that high-impact operations and sensitive data are protected by defense in depth.

Satisfies FR-ORG-009, FR-ORG-010, FR-TRN-002.

Acceptance Criteria (Gherkin)

Scenario: Sensitive action requires step-up authentication
  Given a staff member is signed in with a standard session
  When they attempt a sensitive action (e.g., closing a VIP ticket, exporting bulk PII)
  Then they are challenged for a second factor
  And the action proceeds only after successful step-up

Scenario: Confidential or VIP ticket enforces attribute-based access
  Given a ticket is marked Confidential or VIP
  When a staff member without the matching attribute attempts to open it
  Then access is denied and the attempt is logged
  And the ticket is invisible in that user's lists and search results

Scenario: Exam-gate blocks live ticket handling until certification is passed
  Given a newly onboarded staff member
  When they attempt to take ownership of a live ticket
  Then the system blocks the action until they have passed the required certification exam
  And the gate status is visible to their supervisor

Epic E4 — Files (FILE)

Goal: Provide secure, auditable file handling for both companies and departments — uploads with antivirus scanning, encryption at rest, in-app preview, versioning, time-limited secure download links, size/type limits, and linkage to retention policies. All file operations are inputs to (and outputs of) the AI OCR and summary capabilities in Epic E5 and the proof-of-resolution gate in Epic E2.

US-FILE-001 — Upload files with size and type limits [M]

As a company representative or staff member I want to upload supporting documents within enforced size and type limits So that only safe, manageable files enter the system.

Satisfies FR-FILE-001, FR-FILE-002.

Acceptance Criteria (Gherkin)

Scenario Outline: Upload succeeds within limits and fails outside them
  Given a user is uploading a file
  When the file is of type <Type> and size <Size>
  Then the upload <Result>
  And on rejection, the user is told the specific limit violated

  Examples:
    | Type            | Size   | Result           |
    | application/pdf | 5 MB   | is accepted      |
    | image/png       | 8 MB   | is accepted      |
    | application/exe | 1 KB   | is rejected      |
    | application/pdf | 250 MB | is rejected      |

US-FILE-002 — Antivirus scan and encrypted object storage [M]

As a security officer I want every uploaded file scanned by ClamAV and stored encrypted in object storage So that malware is blocked and data at rest is protected.

Satisfies FR-FILE-003, FR-FILE-004, NFR-SEC-003.

Acceptance Criteria (Gherkin)

Scenario: Clean file is stored encrypted
  Given a user uploads a file that passes ClamAV
  When the scan completes
  Then the file is written to encrypted object storage (MinIO/S3)
  And a stored record links the file to its owning ticket and uploader

Scenario: Infected file is quarantined and rejected
  Given a user uploads a file that ClamAV flags as malicious
  Then the file is quarantined, not made available for download
  And the upload is rejected with a safe error message
  And a security alert is raised and audit-logged

US-FILE-003 — In-app preview and versioning [S]

As a ticket participant I want to preview documents inline and see their version history So that I can review content without downloading and track changes over time.

Satisfies FR-FILE-005, FR-FILE-006.

Acceptance Criteria (Gherkin)

Scenario: Preview a supported file inline
  Given a ticket has an attached file in a preview-supported format
  When a participant with access opens the preview
  Then the file renders inline without requiring a download
  And participants without access cannot preview it

Scenario: New version supersedes the prior one
  Given a participant uploads a new version of an existing file
  Then the prior version is preserved as history
  And the latest version is shown as current
  And the version number, uploader, and timestamp are recorded

US-FILE-004 — Secure, time-limited download links [M]

As a staff member I want to generate signed, expiring download links for files So that I can share evidence externally without exposing the storage layer.

Satisfies FR-FILE-007.

Acceptance Criteria (Gherkin)

Scenario: Signed link expires after its time limit
  Given a staff member generates a signed download link with a time limit
  When the recipient opens the link within the limit and from an allowed context
  Then the file downloads successfully
  And the download event is audit-logged

Scenario: Expired or tampered link is rejected
  Given a signed link has expired or been modified
  When a recipient attempts to use it
  Then the request is rejected with an "expired or invalid" response
  And the rejection is logged

US-FILE-005 — Retention policy linkage [S]

As a records officer I want each file linked to a retention policy aligned with Sindh Archives rules So that the system can preserve, archive, or purge files lawfully.

Satisfies FR-FILE-008, governance notes in /specs/en/22-governance-legal/.

Acceptance Criteria (Gherkin)

Scenario: File inherits retention from its ticket category
  Given a file is attached to a ticket of a given category
  When the file is stored
  Then a retention policy is associated based on category and document type
  And the policy is visible to records officers

Scenario: Retention action executes on schedule
  Given a file has reached its retention horizon
  When the scheduled retention job runs
  Then the file is archived or purged per policy
  And the action is recorded for compliance audit

Epic E5 — AI (11 Capabilities, Pluggable Engine)

Goal: Deliver the eleven locked AI capabilities behind a single pluggable-engine abstraction so that operators can swap providers (Azure OpenAI / Google / AWS, or self-hosted Llama/Qwen via Ollama + vLLM; Tesseract / Google Doc AI / Azure Document Intelligence / AWS Textract for OCR) per data sensitivity, and so that each capability can be enabled or disabled independently. AI augments human accountability; it never replaces a human decision gate. See /specs/en/07-ai-ocr-spec/ for full specifications.

US-AI-001 — Multilingual OCR for scanned documents (EN/UR/SD) [M]

As a staff member I want scanned documents in English, Urdu, or Sindhi to be OCRed into searchable text So that I can search, summarize, and translate evidence even when it arrives as an image.

Satisfies FR-AI-001.

Acceptance Criteria (Gherkin)

Scenario Outline: OCR extracts text in each script
  Given a scanned document is uploaded
  When the OCR pipeline runs
  Then searchable text is extracted with script <Script>
  And the extracted text is indexed for full-text search

  Examples:
    | Script      |
    | Latin (EN)  |
    | Urdu (UR)   |
    | Sindhi (SD) |

Scenario: OCR confidence is recorded
  Given OCR has run on a document
  Then a confidence score is attached to the extraction
  And low-confidence extractions are flagged for manual review

US-AI-002 — Summary, classification, and auto-routing suggestion [M]

As a facilitator I want the system to summarize each ticket, classify it, and suggest routing So that I can triage quickly and consistently.

Satisfies FR-AI-002, FR-AI-003, FR-AI-004.

Acceptance Criteria (Gherkin)

Scenario: Summary and classification are produced on intake
  Given a new ticket is submitted
  When the AI service processes it
  Then a concise summary is generated and attached
  And a category classification and a routing suggestion are proposed with confidence scores
  And the facilitator can accept, edit, or reject each

Scenario: Routing suggestion is auditable
  Given the AI proposed a routing
  When the facilitator overrides it
  Then the original suggestion, the override, and the actor are logged for model review

US-AI-003 — Urgency and sentiment scoring [S]

As a triage officer I want each ticket scored for urgency and sentiment So that time-sensitive or frustrated submitters are prioritized.

Satisfies FR-AI-005.

Acceptance Criteria (Gherkin)

Scenario: Urgency and sentiment are computed at intake and on update
  Given a ticket is submitted or updated
  When the AI service runs
  Then an urgency level and a sentiment label are attached to the ticket
  And tickets flagged as high urgency are surfaced in the triage queue

Scenario: Score influences SLA tier
  Given a ticket is scored as critical urgency
  Then it is routed to the appropriate SLA tier per policy
  And the rationale is visible to the triage officer

US-AI-004 — Draft reply suggestions and translation (EN/UR/SD) [S]

As a staff member I want AI to draft replies I can edit, and to translate correspondence between EN, UR, and SD So that I respond faster and across language barriers.

Satisfies FR-AI-006, FR-AI-009.

Acceptance Criteria (Gherkin)

Scenario: Draft reply is generated and editable
  Given a staff member opens a ticket that needs a response
  When they request a draft
  Then a context-aware draft reply is generated for review
  And the draft is clearly marked as AI-generated until edited or approved by a human
  And sending requires explicit human confirmation

Scenario: Translation is reversible and preserved
  Given a message exists in <Source>
  When the staff member requests translation to <Target>
  Then a translation is produced and shown alongside the original
  And the original is preserved unchanged

  Examples:
    | Source | Target |
    | EN     | UR     |
    | UR     | SD     |
    | SD     | EN     |

US-AI-005 — Duplicate/similarity detection and PII redaction [S]

As a facilitator and a privacy officer I want similar tickets surfaced for deflection and PII redacted before any cloud AI processing So that duplicate work is reduced and personal data is protected.

Satisfies FR-AI-007, FR-AI-010, NFR-SEC-007.

Acceptance Criteria (Gherkin)

Scenario: Similar tickets are surfaced at intake and triage
  Given a new ticket is submitted
  When the similarity service runs
  Then similar open and resolved tickets are listed with similarity scores
  And the facilitator can link, merge, or use them for deflection

Scenario: PII is redacted before cloud processing
  Given a document or message is routed to a cloud-hosted AI provider
  When it leaves the trust boundary
  Then detected PII (CNIC, phone, email, etc.) is masked or tokenized
  And the redaction map is retained on-prem so the original can be restored on return

US-AI-006 — Public chatbot with human handoff, trends/analytics, and MoM action extraction [S]

As a visitor, a leadership user, and a meeting officer I want an AI chatbot for public guidance, AI-driven trends and analytics, and AI extraction of action items from uploaded Minutes of Meeting So that self-service, oversight, and meeting follow-through are all accelerated.

Satisfies FR-AI-008, FR-AI-011, FR-AI-012. MoM flow aligns with Epic E13 (Part 2).

Acceptance Criteria (Gherkin)

Scenario: Chatbot hands off to a human facilitator
  Given a visitor is in a chatbot session that exceeds the bot's confidence or scope
  When the bot offers handoff and the visitor accepts
  Then a live facilitator session or ticket is created
  And the transcript is attached for continuity

Scenario: Trends and analytics are generated from ticket data
  Given the analytics pipeline runs on a schedule
  When leadership opens the analytics dashboard
  Then AI-generated trend insights are displayed (e.g., rising categories, bottleneck departments)
  And each insight links to the underlying metric

Scenario: MoM upload yields structured action items
  Given a meeting officer uploads a Minutes of Meeting document
  When the AI service processes it
  Then action items with owners and due dates are extracted for officer confirmation
  And on confirmation, each action item becomes a sub-task linked to the source ticket

US-AI-007 — Pluggable engine abstraction with per-feature enable flags [M]

As a Platform Operator I want every AI capability behind a single interface with swappable engines and per-feature enable flags So that I can choose providers per data sensitivity and turn features on or off without code changes.

Satisfies FR-AI-013, FR-FFG-001.

Acceptance Criteria (Gherkin)

Scenario Outline: Engine selection is configurable per capability
  Given the platform supports engines <Engine>
  When the operator selects an engine for capability <Capability>
  Then that capability executes against the selected engine
  And switching engines requires no code change

  Examples:
    | Capability | Engine options                                              |
    | LLM        | Azure OpenAI / Google / AWS / self-hosted Llama or Qwen    |
    | OCR        | Tesseract / Google Doc AI / Azure Document Intelligence / AWS Textract |

Scenario: Per-feature flag disables a capability gracefully
  Given an operator disables a feature flag for an AI capability
  When a user attempts to invoke that capability
  Then the capability is hidden or returns a controlled "unavailable" response
  And all dependent flows degrade gracefully
  And no error is exposed to end users

Epic E6 — Internal Communications (COM, Three Tiers)

Goal: Provide staff-only internal communications in three escalating tiers — (1) ticket-scoped private threads tightly coupled to a ticket's lifecycle, (2) an org-wide inbox for one-to-one and group direct messages across any staff, DG, or Secretary, and (3) a full channel-based chat experience (Slack-style: channels per department/topic plus ad-hoc channels, threaded conversations, pins, presence, typing indicators, read receipts, and full-text search). Every message across all three tiers is audit-logged and retained per the records policy.

US-COM-001 — Tier 1: Ticket-scoped private threads [M]

As a ticket's assigned staff and watchers I want a private discussion thread attached to the ticket So that our coordination is captured in context and preserved with the ticket record.

Satisfies FR-COM-001, FR-COM-002.

Acceptance Criteria (Gherkin)

Scenario: Thread is scoped to ticket participants
  Given a ticket with assigned staff and watchers
  When a participant posts a message with an @mention and an attachment
  Then the message is visible only to ticket participants
  And the mentioned user receives a notification
  And the message and attachment are retained with the ticket

Scenario: Thread cannot leave the ticket context
  Given a private thread exists on a ticket
  Then its messages are not visible from any other ticket or from Tiers 2 or 3
  And messages are removed from a participant's view if their access is revoked

US-COM-002 — Tier 2: Org-wide inbox (1:1 and group DMs) [S]

As a staff member I want to send direct messages to any other staff, DG, or Secretary, individually or in a group So that I can coordinate across departments without leaving the Portal.

Satisfies FR-COM-003.

Acceptance Criteria (Gherkin)

Scenario: Direct message across departments
  Given a staff member in department A
  When they start a direct message with a staff member, DG, or Secretary in department B
  Then the conversation is created in the org-wide inbox
  And only the named participants can see it
  And all messages are retained and audit-logged

Scenario: Group DM admits new participants with history policy
  Given an existing group DM
  When a participant is added
  Then the new participant's visibility of prior history follows the configured history-sharing policy
  And the addition is logged

US-COM-003 — Tier 3: Channel-based chat with threads and pins [C]

As a department team I want persistent channels per department or topic, plus ad-hoc channels, threaded replies, and pinned messages So that our conversations are organized and discoverable.

Satisfies FR-COM-004, FR-COM-005.

Acceptance Criteria (Gherkin)

Scenario: Department channel is created and joined
  Given a department exists
  When an administrator creates a department channel
  Then members of that department are auto-joined
  And other staff can request to join per policy

Scenario: Threaded reply and pin
  Given a message exists in a channel
  When a participant replies in a thread or pins the message
  Then the threaded reply is grouped under the parent
  And the pinned message appears in the channel's pinned list
  And both actions are audit-logged

US-COM-004 — Presence, typing, read receipts, and full-text search [S]

As a chat participant I want presence, typing indicators, read receipts, and full-text search across my accessible messages So that I can communicate in real time and find past messages quickly.

Satisfies FR-COM-006.

Acceptance Criteria (Gherkin)

Scenario: Real-time signals reflect participant activity
  Given two participants are in an active conversation
  When one types or reads a message
  Then the other sees typing and read-receipt indicators in real time
  And presence shows each participant's online/away status

Scenario: Search returns only accessible messages
  Given a participant searches for a keyword
  When the search executes
  Then results include only messages from channels, DMs, and threads they can access
  And Urdu and Sindhi keywords are matched correctly via the multilingual search engine

US-COM-005 — Audit logging and retention of all messages [M]

As a compliance officer I want every message across all three tiers audit-logged and retained per policy So that the Portal's internal communications are auditable and lawful.

Satisfies FR-COM-007, NFR-SEC-008.

Acceptance Criteria (Gherkin)

Scenario: Every message is logged at send time
  Given a participant sends a message in any tier
  When the message is sent
  Then an audit record captures sender, recipients, timestamp, channel or ticket, and content hash
  And the record cannot be altered by the sender

Scenario: Retention policy governs lifespan
  Given messages exist across the three tiers
  When the retention horizon for a tier is reached
  Then messages are archived or purged per the records policy
  And the action is logged for compliance

Epic E7 — Notifications (NOT)

Goal: Deliver templated, multilingual notifications across email (Mailjet), SMS, WhatsApp, and in-app channels, with two-way inbound replies that append to the originating ticket, a preference center for digests, quiet hours, and per-channel opt-outs, and rate limiting to prevent abuse and channel fatigue. Notifications are the connective tissue that ties every other module to the user's attention.

US-NOT-001 — Multichannel delivery (email, SMS, WhatsApp, in-app) [M]

As a user (representative or staff) I want notifications delivered through my available channels So that I learn about ticket activity wherever I am.

Satisfies FR-NOT-001.

Acceptance Criteria (Gherkin)

Scenario Outline: Notification is delivered on each enabled channel
  Given a notification event occurs for a user
  When the user has channel <Channel> enabled
  Then the notification is delivered via <Channel>
  And delivery status is recorded

  Examples:
    | Channel   |
    | Email     |
    | SMS       |
    | WhatsApp  |
    | In-app    |

Scenario: Channel failure triggers fallback
  Given a primary channel delivery fails
  Then the system retries per policy
  And after exhausting retries, it attempts a configured fallback channel
  And the failure and fallback are logged

US-NOT-002 — Templated and multilingual notifications [M]

As a localization owner I want every notification rendered from versioned templates in EN, UR, and SD So that messages are consistent, on-brand, and language-correct.

Satisfies FR-NOT-002.

Acceptance Criteria (Gherkin)

Scenario: Template renders in the recipient's preferred language
  Given a notification event occurs
  When the recipient's preferred language is <Lang>
  Then the message is rendered from the template in <Lang>
  And variables (ticket ID, names, dates) are substituted correctly
  And dates display in both Gregorian and Hijri per convention

  Examples:
    | Lang |
    | EN   |
    | UR   |
    | SD   |

Scenario: Template change is versioned
  Given an editor updates a notification template
  Then the prior version is preserved
  And the change, editor, and timestamp are recorded

US-NOT-003 — Two-way inbound replies (email and WhatsApp append to ticket) [S]

As a Company Representative I want to reply directly to an email or WhatsApp notification and have it appended to my ticket So that I can respond without signing in.

Satisfies FR-NOT-003.

Acceptance Criteria (Gherkin)

Scenario: Email reply appends to the originating ticket
  Given a representative received a ticket notification email
  When they reply to that email
  Then the reply body and any attachments are appended as a comment on the originating ticket
  And the assigned staff and watchers are notified
  And the append event is logged

Scenario: Inbound message fails closed when no ticket can be resolved
  Given an inbound reply cannot be matched to a ticket or sender
  Then the system holds it for review rather than discarding
  And a facilitator is notified of the unmatched inbound

US-NOT-004 — Preference center: digests, quiet hours, per-channel opt-out [M]

As a user I want to choose how, when, and how often I am notified So that I get useful alerts without being overwhelmed.

Satisfies FR-NOT-004.

Acceptance Criteria (Gherkin)

Scenario: User configures a digest
  Given a user opens the preference center
  When they select a daily or weekly digest for non-urgent events
  Then non-urgent notifications are batched into the chosen digest
  And urgent events still send immediately

Scenario: Quiet hours suppress non-urgent notifications
  Given a user has set quiet hours
  When a non-urgent notification falls within those hours
  Then it is held and delivered when quiet hours end
  And urgent notifications bypass quiet hours per policy

Scenario: Per-channel opt-out is honored
  Given a user disables a channel
  When a notification would otherwise use that channel
  Then it is not delivered on the disabled channel
  And the user's preference is logged

US-NOT-005 — Rate limiting and throttling [M]

As a Platform Operator I want outbound and inbound notifications rate-limited So that the system is not abused and channels are not exhausted.

Satisfies FR-NOT-005, NFR-SEC-009.

Acceptance Criteria (Gherkin)

Scenario: Outbound rate limiting protects channels
  Given a burst of notifications targets a single recipient or domain
  When the rate exceeds the configured limit
  Then excess notifications are queued or coalesced
  And no channel rate cap is breached

Scenario: Inbound abuse is throttled
  Given repeated inbound replies from the same source in a short window
  When the threshold is exceeded
  Then further inbound from that source is throttled
  And the event is flagged for review

Epic E8 — Integrations (INT)

Goal: Connect the Portal to the external systems it depends on for verification, lookup, official file movement, and identity — NADRA (CNIC verify), SECP (company lookup), FBR (NTN), SRB, PSEB, the NITB e-Office for ticket/MoM-to-file-movement, OIDC single sign-on for government staff, and a public REST API with outbound webhooks for downstream consumers. All integrations are built behind an adapter pattern with idempotency, retries, and circuit breakers so that a downstream outage degrades gracefully rather than failing the user flow. Detailed contracts live in /specs/en/08-integrations-spec/ and /specs/en/12-api-contract/.

US-INT-001 — NADRA CNIC verification [M]

As a registration and verification service I want to verify a representative's CNIC against NADRA So that identity claims are trustworthy before account activation.

Satisfies FR-INT-001.

Acceptance Criteria (Gherkin)

Scenario: CNIC verification returns a deterministic result
  Given a representative has supplied a CNIC
  When the NADRA adapter is invoked
  Then a verified, not-verified, or unable-to-verify result is returned
  And the result, timestamp, and request reference are stored on the representative's record

Scenario: NADRA outage degrades gracefully
  Given the NADRA service is unavailable
  When verification is attempted
  Then the circuit breaker opens after configured failures
  And the registration flow places the account in a "verification pending" state
  And retries resume when the service recovers

US-INT-002 — SECP, FBR, SRB, and PSEB entity lookups [M]

As a verification service I want to look up company registration, tax, and industry-body status across SECP, FBR/NTN, SRB, and PSEB So that the file-first/verify-in-parallel flow can confirm or flag a company.

Satisfies FR-INT-002, FR-ORG-002.

Acceptance Criteria (Gherkin)

Scenario Outline: Each registry lookup enriches the verification record
  Given a company has submitted registration details
  When the <Registry> adapter is invoked with the company's identifier
  Then a normalized lookup result is stored against the verification record
  And the result feeds the parallel verification workflow

  Examples:
    | Registry |
    | SECP     |
    | FBR/NTN  |
    | SRB      |
    | PSEB     |

Scenario: Conflicting results flag the verification
  Given two or more registries return conflicting status
  Then the verification is flagged for manual review
  And the discrepancies are visible to the adjudicator

US-INT-003 — NITB e-Office file movement [S]

As a department officer I want ticket and MoM artifacts to flow into NITB e-Office as official file movements So that Portal activity is recorded in the government's official record system.

Satisfies FR-INT-003.

Acceptance Criteria (Gherkin)

Scenario: Ticket resolution creates an e-Office file movement
  Given a ticket is resolved with proof-of-resolution attached
  When the integration is enabled for the concerned department
  Then a file movement record is created in NITB e-Office
  And the e-Office reference is stored on the ticket
  And the creation is audit-logged

Scenario: Outage does not block the Portal
  Given NITB e-Office is unavailable
  When a file movement is attempted
  Then the movement is queued and retried
  And the Portal ticket flow is not blocked
  And recovery reconciles pending movements idempotently

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

As a government staff member I want to sign in once via OIDC and access the Portal without a separate password So that access aligns with my department's identity provider and 2FA policy.

Satisfies FR-INT-004.

Acceptance Criteria (Gherkin)

Scenario: Staff signs in via the department identity provider
  Given a staff member arrives at the Portal sign-in
  When they choose SSO
  Then they are redirected to the OIDC provider
  And on successful authentication, they are signed in to the Portal
  And their group and role claims are applied

Scenario: Step-up 2FA is enforced for sensitive sessions
  Given the identity provider enforces 2FA
  When the staff member accesses a sensitive area
  Then the second factor is required per provider policy
  And the session is marked as step-up-authenticated

US-INT-005 — Public REST API and outbound webhooks (adapter, idempotency, retries, circuit breakers) [S]

As a downstream consumer (analytics platform, partner department, or integration partner) I want a versioned public REST API and the ability to subscribe to outbound webhooks So that I can build automation on top of Portal events safely.

Satisfies FR-INT-005, FR-INT-006.

Acceptance Criteria (Gherkin)

Scenario: API request is authenticated and idempotent
  Given a partner holds valid API credentials
  When they submit a request with an idempotency key
  Then the request is processed once even if retried
  And responses follow the published API contract and version

Scenario Outline: Webhooks deliver with retries and a circuit breaker
  Given a partner has subscribed to <Event> webhooks
  When the event occurs
  Then a signed webhook is delivered to the registered endpoint
  And on failure, retries follow an exponential backoff up to the configured limit
  And repeated failures open the circuit breaker and pause delivery

  Examples:
    | Event                 |
    | ticket.created        |
    | ticket.resolved       |
    | mom.published         |

Scenario: Webhook payload is verifiable
  Given a partner receives a webhook
  Then the payload includes a signature the partner can verify
  And replay attacks are prevented by timestamp validation
## Epic E9 — Analytics (ANL)

**Goal.** Deliver the nine analytics metric families (volume/throughput, speed, SLA/escalation, quality/outcome, department/staff performance, AI module metrics, engagement/comms, governance/compliance, public transparency) through seven role-scoped dashboards with drill-down, filters, comparative views, scheduled digests, exports, GIS heatmap, anomaly/SLA-breach prediction, saved views, and embeddable widgets — backed by Metabase plus custom ECharts/Recharts.

### US-ANL-001 — Role-scoped analytics dashboard  [M]

**As a** user in any of the seven roles (Super Admin, Dept Admin, DG, Officer, Secretary, Minister/SACM, Company, Public)
**I want** a dashboard tailored to my role showing only the metrics relevant to me
**So that** I can act on the right information without being overwhelmed or exposed to data outside my scope.

#### Acceptance Criteria (Gherkin)

```gherkin
Scenario: Officer sees personal workload and per-shift KPIs
  Given an Officer is logged in to the S&ITD facilitation desk
  When they open their dashboard
  Then they see their open ticket count, average resolution time, SLA-at-risk list, and per-shift throughput
  And they do not see other officers' individually-identifiable performance scores

Scenario: Minister/SACM sees province-wide aggregate KPIs
  Given the Minister/SACM opens the executive dashboard
  When the dashboard renders
  Then they see province-wide volume, FRT/TAT trends, escalation summary, CSAT trend, and department leaderboard
  And all figures respect their oversight scope (notify-only vs action) per department configuration

US-ANL-002 — Drill-down, filter & comparative analysis [M]

As a Dept Admin I want to drill from a summary KPI into individual tickets, filter by department/section/category/date/district/severity, and compare two periods or two departments side by side So that I can investigate root causes of SLA breaches and quality dips.

Acceptance Criteria (Gherkin)

Scenario: Drill from breach summary to ticket list
  Given a Dept Admin views the SLA-breach-by-department chart
  When they click a department bar
  Then a filtered ticket list opens showing every breached ticket for that department in the selected period
  And the same filters can be saved as a named view

US-ANL-003 — Scheduled digests per role cadence [M]

As a senior official I want analytics digests delivered on a role-appropriate schedule (Secretary daily, Minister weekly, Dept Admin daily, DG daily, Officers per-shift) So that I stay informed without logging in constantly, and each digest is configurable.

Acceptance Criteria (Gherkin)

Scenario: Default digest cadences are pre-configured but overridable
  Given the digest scheduler runs with defaults
  Then Secretary receives a daily digest, Minister a weekly digest, Dept Admin a daily digest, DG a daily digest, and Officers a per-shift digest
  And each recipient can change their cadence, channels (email/in-app/SMS/WA), and quiet hours in their preference center

Scenario: Digest is delivered in the recipient's preferred language
  Given a DG has selected Urdu as their preferred language
  When the daily digest is generated
  Then the digest body, KPI labels, and chart legends are rendered in Urdu (RTL)

US-ANL-004 — Export analytics to PDF/Excel/CSV [M]

As a Secretary I want to export any dashboard or chart as PDF, Excel, or CSV So that I can attach figures to briefings, audit records, and Assembly questions.

Acceptance Criteria (Gherkin)

Scenario: Export a dashboard with applied filters
  Given a Secretary has applied a date range and department filter to a dashboard
  When they choose "Export as PDF"
  Then a PDF is generated reflecting the same filters, charts, and data tables
  And the export is audit-logged with the user, scope, and timestamp

US-ANL-005 — Public transparency dashboard (anonymized) [M]

As a member of the public I want to view an anonymized transparency dashboard showing aggregate volumes, resolution rates, average resolution times, and department performance — without exposing any company or individual identity So that I can trust the system is delivering and hold departments accountable.

Acceptance Criteria (Gherkin)

Scenario: Public dashboard exposes no PII
  Given the public transparency dashboard is rendered for an anonymous visitor
  When any chart or its underlying data is inspected
  Then no company name, individual name, ticket ID, or free-text content is exposed
  And small-cell suppression is applied so any group with fewer than the configured minimum size is hidden

US-ANL-006 — GIS district heatmap & SLA-breach prediction [S]

As a Super Admin I want a GIS district heatmap of ticket origin and resolution performance, plus anomaly detection and SLA-breach prediction alerts So that I can target under-served districts and intervene before tickets breach.

Acceptance Criteria (Gherkin)

Scenario: Predicted breach triggers a proactive alert
  Given the prediction model estimates a ticket will breach its SLA within the next 24 hours
  When the estimate crosses the confidence threshold
  Then an alert is raised to the assigned Officer, their DG (watcher), and the Dept Admin digest

Epic E10 — Knowledge Base + SOP (KB)

Goal. Provide a self-service Knowledge Base with articles, downloadable forms, versioned SOPs, AI semantic search, "was this helpful" feedback, deflection tracking, and a service catalog — governed by an authoring workflow with editorial review.

US-KB-001 — Browse & semantic-search KB articles, SOPs and forms [M]

As a Company Representative or public visitor I want to search the Knowledge Base in my own words (including Urdu/Sindhi) and find articles, versioned SOPs, and downloadable forms So that I can resolve common questions myself without filing a ticket.

Acceptance Criteria (Gherkin)

Scenario: Semantic search returns relevant trilingual results
  Given a visitor enters a natural-language query in Sindhi
  When the search runs
  Then ranked results are returned from articles, SOPs, and forms matching intent (not just keywords)
  And each result shows title, summary, language, and last-updated date

Scenario: Downloading a form requires no login
  Given a visitor finds a downloadable form in the service catalog
  When they click download
  Then the latest published version is delivered without requiring authentication

US-KB-002 — KB authoring workflow with editorial review [M]

As a KB Author I want to draft articles and SOPs, submit them for editorial review, and have versions tracked So that only reviewed, current content reaches the public.

Acceptance Criteria (Gherkin)

Scenario: Draft → Review → Publish lifecycle
  Given a KB Author completes a draft SOP
  When they submit it for review
  Then the article moves to "In Review" and a KB Editor is notified
  And on approval the article is published as a new version while prior versions remain archived and accessible

Scenario: Outdated article is flagged for review
  Given a published article has not been reviewed in the configured freshness window
  When the window expires
  Then the article is flagged "Needs Review" and its Authors are notified

US-KB-003 — Deflection tracking & "was this helpful" feedback [S]

As a Dept Admin I want to track article helpfulness and ticket deflection (tickets avoided because the user found the answer) So that I can invest in content that reduces avoidable tickets.

Acceptance Criteria (Gherkin)

Scenario: Helpful vote and deflection are attributed
  Given a visitor views an article surfaced by search
  When they vote "Yes, this was helpful" and does not proceed to file a ticket
  Then a positive helpfulness vote is recorded and a deflection event is attributed to that article

Epic E11 — Multi-channel Intake (MCI)

Goal. Let companies and citizens raise tickets through any channel — email, SMS, WhatsApp, toll-free IVR/voice, or walk-in/offline entry by staff — with automatic deduplication against existing tickets.

US-MCI-001 — Email-to-ticket intake [M]

As a Company Representative I want to send an email to the facilitation desk address and have it become a tracked ticket So that I can raise issues from my normal email workflow.

Acceptance Criteria (Gherkin)

Scenario: Inbound email creates a ticket
  Given an inbound email arrives at the facilitation desk mailbox from a verified sender
  When the intake pipeline processes it
  Then a ticket is created with subject as title, body as description, and attachments preserved
  And a confirmation reply is sent carrying the new tracking ID

Scenario: Reply on an existing thread appends to the ticket
  Given an inbound email references an existing ticket ID in subject or reply headers
  When the pipeline processes it
  Then the email body and attachments are appended as a comment on that ticket, not a new ticket

US-MCI-002 — WhatsApp & SMS-to-ticket intake [M]

As a Company Representative I want to send a message to the official WhatsApp or SMS number and have it raise or update a ticket So that I can use the channel I am most comfortable with.

Acceptance Criteria (Gherkin)

Scenario: WhatsApp message with attachment creates a ticket
  Given a verified contact sends a WhatsApp message with a photo to the official number
  When the message is processed
  Then a ticket is created with the message text and the image attached (AV-scanned)
  And the contact receives a WhatsApp confirmation with the tracking ID

Scenario: Two-way SMS keeps the thread on the ticket
  Given a contact replies by SMS to a ticket notification
  When the reply is received
  Then it is appended as a comment on the originating ticket

US-MCI-003 — Toll-free IVR / voice intake [S]

As a a citizen without internet access I want to call a toll-free number, navigate an IVR, optionally leave a voice recording, and have an agent or speech-to-text convert it into a ticket So that I can raise issues even when I cannot read or type.

Acceptance Criteria (Gherkin)

Scenario: Voice recording becomes a ticket
  Given a caller selects the "register a complaint" IVR option and leaves a voice recording
  When the recording is transcribed (with AI fallback to manual entry)
  Then a ticket is created with the transcript as description and the audio attached
  And the caller receives an SMS with the tracking ID

US-MCI-004 — Walk-in / offline intake by staff with dedup [M]

As a front-desk Officer I want to enter a walk-in complaint on behalf of a visitor, and have the system check for duplicates across channels before creating a new ticket So that the same issue is not tracked multiple times.

Acceptance Criteria (Gherkin)

Scenario: Duplicate detected across channels
  Given a visitor already emailed a complaint about an issue
  When the front-desk Officer enters a walk-in ticket with similar content from the same contact
  Then the system surfaces the existing ticket as a likely duplicate
  And the Officer can choose to merge, link, or proceed as a new ticket, with the choice audit-logged

Scenario: Offline entry syncs when connectivity returns
  Given an Officer enters a ticket while offline
  When connectivity is restored
  Then the ticket is synced with the correct timestamp preserved as the original entry time

Epic E12 — Document Generation + e-Sign (DOC)

Goal. Generate trilingual official letters and resolution certificates on government letterhead, PKI-digitally sign them, and attach a verifiable QR code so recipients and third parties can confirm authenticity — using the official-in-office as of the document date.

US-DOC-001 — Generate trilingual official letters & resolution certificates [M]

As an Officer I want to generate an official letter or resolution certificate on S&ITD (or concerned department) letterhead in English, Urdu, or Sindhi So that correspondence with companies and other departments is formal, branded, and consistent.

Acceptance Criteria (Gherkin)

Scenario: Generate a resolution certificate from a ticket
  Given a ticket is in Resolved state with proof-of-resolution evidence attached
  When the Officer chooses "Generate Resolution Certificate"
  Then a trilingual-ready document is produced on letterhead with ticket ID, company details, resolution summary, and the official-in-office as of today
  And the document is saved as a versioned attachment on the ticket

Scenario: Letter language follows recipient preference unless overridden
  Given a company's preferred language is Sindhi
  When an Officer generates a letter without specifying language
  Then the letter renders in Sindhi (RTL) by default, with the Officer able to switch languages before signing

US-DOC-002 — PKI digital signing of official documents [M]

As an authorized signatory (Secretary / DG / designated Officer) I want to digitally sign generated documents using a PKI credential So that recipients can cryptographically verify the document was issued by the stated authority and has not been tampered with.

Acceptance Criteria (Gherkin)

Scenario: Signing produces a verifiable signature
  Given an authorized signatory opens an unsigned letter and authenticates their PKI credential (with 2FA)
  When they sign the document
  Then a PKI digital signature is applied with certificate metadata (signer DN, timestamp, validity period)
  And the signed document is immutable thereafter

US-DOC-003 — QR verification of letters (anti-forgery) [M]

As a recipient or third party I want to scan or look up the QR code on an official letter and confirm whether it is genuine and unmodified So that I cannot be defrauded by forged government correspondence.

Acceptance Criteria (Gherkin)

Scenario: Genuine letter verifies successfully
  Given a recipient scans the QR code on a signed letter
  When the verification portal resolves the code
  Then a public page confirms issuance date, signing authority, ticket reference, and current document status, and that the file hash matches

Scenario: Tampered or unknown QR is rejected
  Given a QR code resolves to no record or to a record whose hash differs from the presented file
  When the verification portal checks it
  Then the page displays a clear "Could not verify" warning and logs the attempt

Epic E13 — Hearings + TRI + MoM (MTG)

Goal. Enable tripartite (Company + S&ITD + Department) meetings in physical, virtual, or hybrid form with AI-drafted agendas, then capture Minutes of Meeting via an upload-first workflow where OCR + AI extract structured action items that become sub-tasks, with a sensitive/VIP approval gate, auto-share to participants, acknowledgment tracking, and full versioning/audit.

US-MTG-001 — Request & schedule a TRI meeting (hybrid) [M]

As an Officer or DG I want to request a tripartite meeting from a stalled ticket and schedule it as physical, virtual, or hybrid So that all three parties can resolve the issue together.

Acceptance Criteria (Gherkin)

Scenario: Hybrid TRI meeting is scheduled
  Given a ticket is stalled and an Officer selects "Request TRI Meeting"
  When they add the Company rep, the concerned Department rep(s), and an S&ITD facilitator, and choose "Hybrid"
  Then a meeting record is created linked to the ticket with location, virtual link (Zoom/Meet/Teams as configured), date/time, and participants

Scenario: Participants cannot be missing
  Given a TRI request omits the concerned Department representative
  When the Officer tries to confirm
  Then the system blocks confirmation and prompts for the missing party

US-MTG-002 — AI-drafted agenda + calendar invites & reminders [M]

As the S&ITD facilitator I want the system to draft an agenda from the ticket history and uploads, send calendar invites, and send reminders to all participants So that the meeting is productive and well-attended.

Acceptance Criteria (Gherkin)

Scenario: Agenda is drafted and editable
  Given a TRI meeting is created from a ticket
  When the facilitator opens the meeting
  Then an AI-drafted agenda is presented summarizing history, open questions, and uploaded evidence
  And the facilitator can edit the agenda before sending invites

US-MTG-003 — MoM upload-first with OCR + AI action-item extraction [M]

As an Officer I want to upload the MoM in the department's own format (PDF/Word/images), have OCR and AI extract structured action items (owners + due dates) and a summary, then confirm before publishing So that minutes are captured faithfully while still becoming structured, trackable data.

Acceptance Criteria (Gherkin)

Scenario: Scanned MoM is OCRed and action items extracted
  Given an Officer uploads a scanned PDF MoM
  When processing completes
  Then OCR (with multilingual support) extracts the text, AI proposes a summary, and a list of action items each with owner and due date is presented for confirmation

Scenario: Officer confirms or corrects extracted items
  Given AI-proposed action items are displayed
  When the Officer reviews them
  Then they can edit owner, due date, and text, remove false positives, or add missed items, before confirming

US-MTG-004 — Confirmed action items become ticket sub-tasks [M]

As an Officer I want each confirmed MoM action item to become a sub-task on the originating ticket, assigned to its owner with a due date So that commitments made in the meeting are tracked to completion like any other work item.

Acceptance Criteria (Gherkin)

Scenario: Action items spawn sub-tasks
  Given the Officer confirms the action-item list
  When they publish (or, for sensitive/VIP, when approval is granted)
  Then each action item creates a sub-task on the ticket assigned to the stated owner with the stated due date
  And the sub-tasks appear on the owner's dashboard and SLA tracking

US-MTG-005 — Sensitive/VIP approval gate, publish & auto-share with acknowledgment [M]

As a Chair or DG I want MoMs on sensitive/VIP tickets to require my approval before publishing, and on publish to auto-share to all participants with acknowledgment tracking So that sensitive content is controlled and all parties are demonstrably informed.

Acceptance Criteria (Gherkin)

Scenario: Sensitive ticket MoM requires approval
  Given the ticket is flagged Sensitive or VIP
  When the Officer tries to publish the MoM
  Then the system routes the MoM to the Chair/DG for approval and blocks auto-share until approved

Scenario: Publish auto-shares and tracks acknowledgments
  Given a MoM is published (directly or after approval)
  When publish completes
  Then all participants receive the MoM via email, in-app, SMS, and WhatsApp
  And the system records each participant's acknowledgment (or non-acknowledgment after the reminder window)
  And the MoM is permanently attached, versioned, and audit-logged on the ticket

US-MTG-006 — Recording consent & multilingual translation [S]

As a facilitator I want to capture explicit consent before recording a virtual meeting, and to translate the MoM and action items across EN/UR/SD So that recordings are lawful and participants can read minutes in their preferred language.

Acceptance Criteria (Gherkin)

Scenario: Recording cannot start without consent
  Given a virtual meeting is about to be recorded
  When the host clicks record
  Then every connected participant is prompted for consent, and recording proceeds only after all required participants consent

Epic E14 — Suggestion & Content Portal (SUG)

Goal. Provide a suggestion box for ideas (distinct from complaints), broadcast circulars and announcements, host a versioned document repository, and apply moderation.

US-SUG-001 — Public suggestion box (ideas, not complaints) [M]

As a Company Representative or citizen I want to submit a suggestion or idea (separate from the complaints/ticket flow), optionally anonymously So that I can contribute improvements without it being treated as a grievance.

Acceptance Criteria (Gherkin)

Scenario: Anonymous suggestion is accepted
  Given a visitor chooses "Submit anonymously"
  When they submit a suggestion
  Then the suggestion is stored with no identity linkage, moderated, and considered for the public ideas board
  And the system rate-limits submissions to deter spam

Scenario: Identified suggestion is acknowledged
  Given a logged-in company rep submits a suggestion with contact details
  When submission completes
  Then they receive an acknowledgment and a reference they can use to track status

US-SUG-002 — Circulars & announcements broadcast [M]

As a Super Admin or Dept Admin I want to publish circulars and announcements that broadcast to relevant audiences (all companies, a department, a segment) So that authoritative information reaches the right people.

Acceptance Criteria (Gherkin)

Scenario: Targeted broadcast
  Given an Admin composes a circular and selects audience "All SECP-registered companies in IT sector"
  When they publish
  Then the circular is delivered via in-app banner and chosen channels (email/SMS/WA) to the selected audience, and archived in the content portal

US-SUG-003 — Versioned document repository with moderation [S]

As a Content Editor I want a versioned document repository with a moderation queue for user-submitted content So that only approved, current documents are publicly visible and history is preserved.

Acceptance Criteria (Gherkin)

Scenario: New version supersedes the old
  Given an editor uploads a new version of an existing repository document
  When they publish
  Then the new version becomes current, the previous version is archived but accessible, and a changelog entry is recorded

Epic E15 — Training & Certification (TRN)

Goal. Provide an LMS-lite where staff complete training courses and quizzes, earn exam-gated certifications required before handling live tickets, and re-certify before expiry.

US-TRN-001 — Staff training courses & quizzes [M]

As a Staff Officer I want to enroll in training courses, consume content, and take quizzes So that I am prepared to handle facilitation desk duties to standard.

Acceptance Criteria (Gherkin)

Scenario: Course completion is recorded
  Given an Officer completes all modules of a course and passes its quiz at or above the pass mark
  When the final quiz is submitted
  Then completion is recorded against their profile with score and timestamp

US-TRN-002 — Exam-gated certification before handling live tickets [M]

As a Super Admin I want to require that an Officer passes the certification exam before they can be assigned any live ticket So that only qualified staff interact with companies.

Acceptance Criteria (Gherkin)

Scenario: Uncertified officer cannot receive assignments
  Given an Officer has not passed the required certification exam
  When auto-routing or manual assignment attempts to assign them a live ticket
  Then the assignment is blocked and a message explains the certification requirement

Scenario: Passing the exam unlocks assignment
  Given the same Officer subsequently passes the certification exam
  When assignment is next attempted
  Then the Officer becomes eligible and the assignment proceeds

US-TRN-003 — Certification expiry & re-certification [S]

As a Dept Admin I want certifications to expire on a defined cadence and require re-certification, with advance warnings So that staff knowledge stays current.

Acceptance Criteria (Gherkin)

Scenario: Expiry warning and grace handling
  Given an Officer's certification expires in 14 days
  When the warning threshold is reached
  Then reminders are sent to the Officer and their Dept Admin
  And if not re-certified by expiry, the Officer is moved to read-only ticket access until they pass again

Epic E16 — Brand & Officials CMS (OFC)

Goal. Manage dynamic records for Minister, Secretary, and DG (name, photo, effective dates, message) that propagate to the site, letters, and dashboards; guarantee historical accuracy through date-aware letterheads; and provide a media library, brand/theme config, and an approval workflow.

US-OFC-001 — Dynamic officials records CMS [M]

As a Brand Editor I want to create and maintain records for the Minister, Secretary, and DG including name, photo, effective dates, and message So that the right official appears across the portal at all times.

Acceptance Criteria (Gherkin)

Scenario: Effective-dated record activates automatically
  Given a new DG record has an effective date of tomorrow
  When that date arrives
  Then the new DG becomes the current official across the public site, letters, and dashboards, and the previous DG moves to historical records

US-OFC-002 — Date-aware letterhead for historical accuracy [M]

As an Officer I want letters and certificates to display the officials who were in office on the document's effective date, even when re-generated later So that historically accurate correspondence cannot be silently re-attributed to current officials.

Acceptance Criteria (Gherkin)

Scenario: Regenerated letter retains historical officials
  Given a letter was originally issued on a date when a different Secretary was in office
  When the letter is regenerated or re-printed months later
  Then the letterhead still shows the official who held the role on the original effective date

US-OFC-003 — Media library & brand/theme configuration [S]

As a Brand Editor I want a central media library and configurable brand/theme (colors, logo lockup, Ajrak motifs) So that visual identity is consistent and updatable in one place.

Acceptance Criteria (Gherkin)

Scenario: Theme change propagates
  Given a Brand Editor updates the primary theme color
  When the change is approved and published
  Then the new theme applies across the public site and staff portal on next render, with the previous theme versioned

US-OFC-004 — Officials approval workflow & propagation [M]

As a Super Admin I want changes to senior-official records to go through an approval workflow before propagating So that no single user can unilaterally change who appears as Minister/Secretary/DG.

Acceptance Criteria (Gherkin)

Scenario: Change requires approval
  Given a Brand Editor submits a change to the Minister record
  When they save
  Then the change is queued for Super Admin approval and does not propagate until approved

Scenario: Approved change propagates atomically
  Given an official-record change is approved
  When approval completes
  Then the change propagates to the public site, letters, and dashboards in a single transaction, and the propagation is audit-logged

Epic E17 — Feature Flags (FFG)

Goal. Make every product capability toggleable by a Super Admin per department and per environment; ensure code paths are gated by flags with safe default states, and audit every flag change.

US-FFG-001 — Super Admin toggles features per department & environment [M]

As a Super Admin I want to enable or disable any capability per department and per environment (dev/staging/prod) So that I can roll out features gradually and disable risky ones instantly without a deploy.

Acceptance Criteria (Gherkin)

Scenario: Department-scoped toggle
  Given a Super Admin opens the feature-flag console for the "MoM AI extraction" flag
  When they enable it for the S&ITD department only and save
  Then the capability becomes available to S&ITD and remains off for all other departments

Scenario: Environment-scoped kill switch
  Given a critical issue is detected in production with the "WhatsApp intake" flag
  When the Super Admin flips the flag off in the production environment
  Then WhatsApp intake is disabled immediately (no deploy) and affected users see a clear "temporarily unavailable" state

US-FFG-002 — Flags gate code paths with safe default states [M]

As a Engineer I want every gated code path to consult the flag service and to fall back to a safe default if the flag service is unreachable So that a flag-service outage cannot enable an unintended feature.

Acceptance Criteria (Gherkin)

Scenario: Flag service unreachable yields fail-safe default
  Given the flag service is temporarily unreachable
  When a gated code path evaluates a flag
  Then the configured fail-safe default is used (off for non-essential features, on for critical paths) and the event is logged

US-FFG-003 — Audited flag changes [M]

As a Auditor I want every flag change — who, what, before/after, scope, timestamp — recorded immutably So that flag operations are traceable for governance and incident review.

Acceptance Criteria (Gherkin)

Scenario: Flag change is captured in the audit log
  Given any user with rights changes a flag value
  When the change is committed
  Then an immutable audit entry is written capturing actor, flag key, previous value, new value, scope (dept/env), and timestamp
  And the entry appears in the governance/compliance analytics and cannot be edited or deleted

Traceability

Representative mapping from Epic → key Functional Requirement IDs → key User Story IDs → acceptance-criteria (Scenario) count → Test Case document reference. Not exhaustive; full per-requirement traceability lives in 02-functional-reqs/ and 13-test-strategy/.

Totals (E9–E17). 35 user stories · 52 acceptance-criteria scenarios · 9 epics.