# Business requirements document

> SYNTHETIC REFERENCE • SAMPLE-PENTASCOPE-MASTER • v1.0.0 • 2026-09-08 • Draft • all 96 cases Not Run. This is a proposed learning and acceptance pack, not customer source truth, test evidence or release approval. No project is created or seeded by opening it.

## Document control and authority

Artifact BRD-MASTER-001; version 1.0.0; owner role Product Owner; reviewer role Business Analyst and Test Lead; status Draft; approval actor/date unset. The sample namespace is SAMPLE-PENTASCOPE-MASTER; it is intentionally not a real server project ID. Every proposed rule below is a **recommendation** grounded in local product surfaces, not an approved customer obligation. See source-manifest.json for file paths, snapshot versions and hashes. Any adopted copy must supply project-owned source references before generation or execution gates can pass.

## Executive business purpose

PentaScope connects source documents, requirements decisions, test design, browser execution, evidence, defects, retests and release decisions. The business outcome is a reviewable chain from an approved obligation to observed behavior. The product is a quality and requirements application; it does not implement an ERP customer's business transactions itself.

The sample journey starts with a named account and an empty project. The business analyst explicitly uploads a versioned BRD or SRS, resolves ambiguities and submits requirements for review. A test lead designs or imports cases, verifies coverage and prepares an approved safe target. An authorized agent or tester records actual execution. A reviewer triages a failed expectation, engineering delivers an identified build, QA retests that build and a named release owner decides readiness.

## Business problem and value

- Requirements scattered across files lose provenance and approval context; source IDs/hashes and decision history make obligations reviewable.
- Test counts are often confused with proof; separate designed/approved/executed/passed coverage keeps the decision honest.
- A fixed issue can be closed against the wrong build; exact-build retest evidence prevents premature closure.
- Shared tokens and cross-project caches leak responsibility or data; named membership and project scope preserve accountability.
- Unbounded AI retries and unsupported output increase cost and uncertainty; registered task policy and validation constrain both.

## Stakeholders and responsibilities

- Sponsor / Product Owner: define business outcomes, accept scope and resolve blocking assumptions; name a release owner.
- Business Analyst / requirements manager: inventory sources, preserve mandatory obligations, resolve findings and maintain immutable requirement revisions.
- Test Lead / tester: approve test design, choose risk coverage, own test data and evidence quality, maintain execution logs.
- Engineer: deliver fixes with build and delivery references; engineering claims are inputs to retest, not acceptance evidence.
- Named reviewer: perform the permitted review decisions; this is a responsibility granted by capabilities, not a separate membership role.
- Operator / security owner: manage isolated infrastructure, secret references, policies, backups and failure fixtures.
- Viewer: read authorized project data and evidence without mutating it.
- Widget/Agent integrations: perform narrowly scoped capture or execution actions under restricted service keys.

## Scope

In scope: identity, sessions/MFA, memberships/service keys, project isolation, typed intake, durable analysis, obligation coverage, requirements and story revisions, test import/design, execution preview/commands/credentials, assertions/evidence, defects/retest, impact/coverage/release, export/handoff, schedules/webhooks, assistant/AI governance, generated presentation media, bilingual accessibility and operations.

Out of scope: implementing external customer systems; live customer data; auto-seeding a project with this pack; direct vendor billing or pricing promises; running invasive production security/load tests; legal policy invention; external emails/webhooks/paid model calls without explicit authorization; claiming every deployed bug has been found.

## Proposed measurable business outcomes

- 100% of adopted mandatory source obligations have explicit reviewed disposition; owner Business Analyst; source ledger denominator frozen by version/hash.
- 100% of critical adopted criteria have approved test designs before execution sign-off; owner Test Lead; denominator is current in-scope critical criteria.
- 100% of claimed passing cases have attributable real observations and evidence; owner Test Lead; measure evidence-complete passes / claimed passes.
- 0 unauthorized project-data reads or writes in the adopted isolation matrix; owner Security Lead; scope limited to actual executed cases.
- 100% of closed defects reference valid matching-build retest evidence under current closure policy; owner Release Owner.
- AI cost per accepted artifact, artifact review rejection rate and source coverage completion time are measured; numeric business targets require sponsor decisions before acceptance.

These targets are proposed acceptance recommendations. No measurements have been performed. Do not interpret a 100% design-link count as achievement of the business outcomes above.

## Business rules and obligation ledger

Each BR maps to one OBL and a detailed REQ/US; its three acceptance criteria map to distinct cases. The ledger records **draft formal disposition**, not a reviewed exclusion or an automated completeness assertion about other projects.

### BR-001 — Named account registration and recovery

People use their own verified account; invalid registration and recovery input never grants project access.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: account holder. Source: SRC-001 (`pentascope-be/lib/account-auth.ts`). Obligation OBL-001 → REQ-001 → US-001. Acceptance cases: TC-001, TC-002, TC-003.

### BR-002 — Session revocation and MFA

Account sessions and MFA operations validate current identity and expose no reusable secret after setup.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: account holder. Source: SRC-002 (`pentascope-be/app/api/account-mfa/route.ts`). Obligation OBL-002 → REQ-002 → US-002. Acceptance cases: TC-004, TC-005, TC-006.

### BR-003 — Project creation and strict data isolation

A new project begins empty and every project read/write uses the authenticated selected project.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner. Source: SRC-003 (`pentascope-be/app/api/account-projects/route.ts`). Obligation OBL-003 → REQ-003 → US-003. Acceptance cases: TC-007, TC-008, TC-009.

### BR-004 — Membership and invitation governance

Only authorized owners manage named memberships; invitations and revocation preserve project ownership and least privilege.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner. Source: SRC-004 (`pentascope-be/app/api/project-members/route.ts`). Obligation OBL-004 → REQ-004 → US-004. Acceptance cases: TC-010, TC-011, TC-012.

### BR-005 — Restricted integration keys

Widget and Agent credentials are restricted project service identities, never substitutes for a person or owner membership.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / service agent. Source: SRC-005 (`pentascope-be/db/runtime.ts`). Obligation OBL-005 → REQ-005 → US-005. Acceptance cases: TC-013, TC-014, TC-015.

### BR-006 — Typed document intake and file safety

Explicit project-owned BRD, SRS and test-case uploads validate type, size and file content before analysis.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor. Source: SRC-006 (`pentascope-be/app/api/project-documents/route.ts`). Obligation OBL-006 → REQ-006 → US-006. Acceptance cases: TC-016, TC-017, TC-018.

### BR-007 — Durable analysis and recovery

Document work uses durable project-scoped jobs, bounded retries and honest failure states without replacing partial validated work with a misleading summary.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor / operator. Source: SRC-007 (`pentascope-be/lib/analysis-job-queue.ts`). Obligation OBL-007 → REQ-007 → US-007. Acceptance cases: TC-019, TC-020, TC-021.

### BR-008 — Source obligation coverage and gaps

Every mandatory source obligation receives an explicit disposition before BRD-derived SRS approval; unsupported assumptions stay visible.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: requirements manager. Source: SRC-008 (`pentascope-be/lib/document-analysis-policy.ts`). Obligation OBL-008 → REQ-008 → US-008. Acceptance cases: TC-022, TC-023, TC-024.

### BR-009 — Detailed BRD to SRS transformation

Draft SRS preserves sourced business meaning and supplies actors, flows, data rules, exceptions and observable acceptance criteria without inventing business truth.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: business analyst. Source: SRC-009 (`pentascope-be/skills/pentascope-requirements-to-quality/references/stage-contracts.md`). Obligation OBL-009 → REQ-009 → US-009. Acceptance cases: TC-025, TC-026, TC-027.

### BR-010 — Requirement decisions and immutable revisions

Explicit authorized review decisions govern requirement status, preserve revision history and invalidate downstream work when source meaning changes.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: requirements manager. Source: SRC-010 (`pentascope-be/app/api/requirements-management/route.ts`). Obligation OBL-010 → REQ-010 → US-010. Acceptance cases: TC-028, TC-029, TC-030.

### BR-011 — Project SRS navigation and explicit links

SRS navigation and traceability show only actual project records and preserve unmapped relationships as visible gaps.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: viewer. Source: SRC-011 (`pentascope-be/app/api/project-traceability/route.ts`). Obligation OBL-011 → REQ-011 → US-011. Acceptance cases: TC-031, TC-032, TC-033.

### BR-012 — Story change and language preservation

Story edits and translations preserve source lineage, business obligations and immutable prior meaning; translated content is reviewable.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor. Source: SRC-012 (`pentascope-be/app/api/story-translate/route.ts`). Obligation OBL-012 → REQ-012 → US-012. Acceptance cases: TC-034, TC-035, TC-036.

### BR-013 — Imported test cases retain identity and quality gaps

Imported cases preserve original identity and content, map only supported requirements and expose duplicates or missing test design fields.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester. Source: SRC-013 (`pentascope-be/lib/phase1-quality.ts`). Obligation OBL-013 → REQ-013 → US-013. Acceptance cases: TC-037, TC-038, TC-039.

### BR-014 — Risk-based test design and delta generation

Generated tests have distinct risk-based objectives, precise criterion links, reproducible steps and observable outcomes; design does not record execution.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester. Source: SRC-014 (`pentascope-be/app/api/story-test-generation/route.ts`). Obligation OBL-014 → REQ-014 → US-014. Acceptance cases: TC-040, TC-041, TC-042.

### BR-015 — Test library selection and approval readiness

Selections resolve current project-owned cases and distinguish approved browser-ready, blocked and manual-only work.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester. Source: SRC-015 (`pentascope-be/lib/test-library.ts`). Obligation OBL-015 → REQ-015 → US-015. Acceptance cases: TC-043, TC-044, TC-045.

### BR-016 — Execution preview bound to target and versions

A confirmed preview binds selected cases, membership version, target and credentials; changes require fresh review before queueing.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester. Source: SRC-016 (`pentascope-be/app/api/execution-previews/route.ts`). Obligation OBL-016 → REQ-016 → US-016. Acceptance cases: TC-046, TC-047, TC-048.

### BR-017 — Credential storage and scoped leases

Test credentials are encrypted server-side and leased only through authorized Agent execution scope; ordinary reads expose metadata only.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / service agent. Source: SRC-017 (`pentascope-be/app/api/project-credentials/[id]/lease/route.ts`). Obligation OBL-017 → REQ-017 → US-017. Acceptance cases: TC-049, TC-050, TC-051.

### BR-018 — Command claims, progress and recovery

Agents execute only authorized safe commands, keep attributable progress and recover from interruption without duplicate terminal results.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: agent:execute. Source: SRC-018 (`pentascope-be/lib/test-command-service.ts`). Obligation OBL-018 → REQ-018 → US-018. Acceptance cases: TC-052, TC-053, TC-054.

### BR-019 — Verifiable assertions and private evidence

The backend computes assertion outcomes from actual receipts and never accepts an unsupported pass; evidence is project-scoped and expires by policy.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: agent:execute / tester. Source: SRC-019 (`pentascope-be/lib/execution-evidence.ts`). Obligation OBL-019 → REQ-019 → US-019. Acceptance cases: TC-055, TC-056, TC-057.

### BR-020 — Defect capture and human triage

Defects record reproducible observations and evidence; authorized human decisions separate confirmed fixes from rejected reports.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester / editor. Source: SRC-020 (`pentascope-be/app/api/issues/[id]/route.ts`). Obligation OBL-020 → REQ-020 → US-020. Acceptance cases: TC-058, TC-059, TC-060.

### BR-021 — Fix delivery and exact-build retest

A defect cannot close until a verified fully passing retest proves the fix on the delivered build and correct case lineage.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor / tester. Source: SRC-020 (`pentascope-be/app/api/issues/[id]/route.ts`). Obligation OBL-021 → REQ-021 → US-021. Acceptance cases: TC-061, TC-062, TC-063.

### BR-022 — Change impact and regression selection

Impact derives from explicit current links and identifies affected requirements, cases and downstream records without hiding unknown relationships.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor. Source: SRC-021 (`pentascope-be/lib/project-impact-engine.ts`). Obligation OBL-022 → REQ-022 → US-022. Acceptance cases: TC-064, TC-065, TC-066.

### BR-023 — Coverage arithmetic and release decisions

Designed, approved, executed, passed and evidenced coverage are separate measurements; critical gaps block release despite a high aggregate score.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner. Source: SRC-022 (`pentascope-be/app/api/lifecycle/route.ts`). Obligation OBL-023 → REQ-023 → US-023. Acceptance cases: TC-067, TC-068, TC-069.

### BR-024 — Portable exports and controlled handoff

Exports and handoffs retain IDs, versions, status and project lineage while excluding secrets and unsupported readiness claims.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / editor. Source: SRC-023 (`pentascope-be/app/api/validation-transfer/route.ts`). Obligation OBL-024 → REQ-024 → US-024. Acceptance cases: TC-070, TC-071, TC-072.

### BR-025 — Scheduled execution with renewed readiness

Schedules are project-owned, use validated cases/targets and do not execute stale or unauthorized work after relevant state changes.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner. Source: SRC-024 (`pentascope-be/app/api/test-schedules/route.ts`). Obligation OBL-025 → REQ-025 → US-025. Acceptance cases: TC-073, TC-074, TC-075.

### BR-026 — Safe webhook delivery and retry

Webhook destinations follow exact-host outbound policy and delivery/retry state records actual transport outcomes.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / operator. Source: SRC-025 (`pentascope-be/lib/webhook-delivery.ts`). Obligation OBL-026 → REQ-026 → US-026. Acceptance cases: TC-076, TC-077, TC-078.

### BR-027 — Grounded and bounded assistant plans

Agent plans use authenticated project sources and allowed targets, explain missing inputs and stay within the approved safe execution mission.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: tester. Source: SRC-026 (`pentascope-be/app/api/agent/plan/route.ts`). Obligation OBL-027 → REQ-027 → US-027. Acceptance cases: TC-079, TC-080, TC-081.

### BR-028 — Governed AI output, privacy and budgets

AI operations use task-specific policy, validated structured output, bounded provider attempts and usage metadata without saving source bodies or secrets in usage receipts.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / operator. Source: SRC-027 (`pentascope-be/lib/ai-task-registry.ts`). Obligation OBL-028 → REQ-028 → US-028. Acceptance cases: TC-082, TC-083, TC-084.

### BR-029 — Private generated media and real content validation

Generated presentation images are real validated media stored privately in the selected project and are never evidence of a test execution.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: editor. Source: SRC-028 (`pentascope-be/app/api/ai-images/route.ts`). Obligation OBL-029 → REQ-029 → US-029. Acceptance cases: TC-085, TC-086, TC-087.

### BR-030 — Accessible bilingual and responsive workspace

English and Arabic routes preserve task context; core controls remain usable by keyboard and in narrow screens with accurate loading, empty and error states.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: viewer / tester. Source: SRC-029 (`pentascope-fe/lib/localized-route.mjs`). Obligation OBL-030 → REQ-030 → US-030. Acceptance cases: TC-088, TC-089, TC-090.

### BR-031 — Readiness, backups and recovery operations

Operations distinguish process liveness from required data/storage readiness and validate recovery against a consistent isolated database/object-store snapshot.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: operator. Source: SRC-030 (`pentascope-be/app/api/ready/route.ts`). Obligation OBL-031 → REQ-031 → US-031. Acceptance cases: TC-091, TC-092, TC-093.

### BR-032 — Auditability and sensitive-data minimization

Business mutations and failures remain attributable to project, actor, operation and time while operational views exclude secret/source-body leakage.

Classification: recommendation. Priority: Must for this proposed master scope; risk: High. Accountable actor: owner / operator. Source: SRC-031 (`pentascope-be/lib/system-log.ts`). Obligation OBL-032 → REQ-032 → US-032. Acceptance cases: TC-094, TC-095, TC-096.

## Assumptions and constraints

- ASSUMPTION-001: a disposable environment and authorized named testers will be provided. If false, execution remains blocked.
- ASSUMPTION-002: source authors will resolve product-specific rules and translations. If false, the generated artifacts remain Draft.
- ASSUMPTION-003: local controlled provider/worker/transport fixtures are available for negative tests. If absent, mark those cases Blocked rather than paying for or contacting a live service.
- ASSUMPTION-004: all fixture accounts, records and mailboxes are synthetic and controlled by the test team. Example domains and IDs confer no authority.
- CONSTRAINT-001: the backend owns authorization, database, storage and provider work; browser code uses its frontend proxy.
- CONSTRAINT-002: this master reference is a read-only static learning artifact. Runtime import and review are explicit separate user actions.

## Risk register and response

- RISK-001 (Critical): tenant leakage. Mitigation: independent A/B fixtures, server-side scope checks and negative read/write tests; owner Security Lead.
- RISK-002 (Critical): fabricated readiness. Mitigation: exact case/build/receipt checks, separate coverage denominators and open critical gates; owner Test Lead.
- RISK-003 (High): source obligation loss. Mitigation: immutable sources, obligation ledger and source coverage receipt; owner Business Analyst.
- RISK-004 (High): stale edits or repeated execution. Mitigation: version checks, preview binding, command claims and bounded retry; owner Engineering.
- RISK-005 (High): credentials or source text leaking into prompts/logs/exports. Mitigation: secret references, redaction and scoped private storage; owner Security Lead.
- RISK-006 (High): a production target is used accidentally. Mitigation: approved manifest, visible target/build and disposable data namespace; owner Environment Owner.

## Change control and acceptance

Adoption starts as a new Draft version with a named owner. Record the changed business rule, rationale, source/version, affected requirement/criterion IDs and required reviewers. Recompute traceability, invalidate stale approval and select regression from explicit links. A business rule is accepted only after an authorized decision and any required evidence; no status in this delivered pack is Approved.

## Open business decisions

### GAP-001 — Business authority and scope approval

Owner: Product owner. Severity: Blocking. Status: Open. These are synthetic proposed acceptance obligations. Supply project-owned BRD/SRS references and approve the adopted scope before any real project artifact is Approved.

### GAP-002 — Target build, routes and credentials

Owner: Test lead. Severity: Blocking. Status: Open. Record the actual frontend/backend URLs, build revisions, authorized route map, environment, memberships and secret-store references. Sample IDs and placeholder URLs are not runnable targets.

### GAP-003 — Performance and capacity

Owner: Product owner / operations. Severity: Blocking for performance sign-off. Status: Open. Choose workload, data volume, concurrency, latency percentiles, measurement duration and resource limits. No production performance target is claimed here.

### GAP-004 — Availability and recovery objectives

Owner: Operations / sponsor. Severity: Blocking for operations sign-off. Status: Open. Approve RPO/RTO, maintenance expectations, backup frequency and restore responsibility, then measure a real sandbox restore.

### GAP-005 — Retention and deletion rules

Owner: Data owner. Severity: Blocking for privacy sign-off. Status: Open. Define per-entity retention, evidence expiry, export retention, deletion/restore behavior and applicable data obligations. This pack invents no legal policy.

### GAP-006 — Accessibility acceptance standard

Owner: Product owner / accessibility lead. Severity: Blocking for accessibility sign-off. Status: Open. Confirm formal conformance level, assistive technologies, supported browsers and devices. Keyboard and narrow-screen cases are concrete checks, not a certification.

### GAP-007 — Execution safety and external services

Owner: Test lead / environment owner. Severity: Blocking. Status: Open. Approve safe target/data/action scope, forbidden actions, concurrency, cleanup, email sink, outbound fixture policy and permitted AI spend. This pack requires local fixtures by default.

### GAP-008 — Reviewer separation and capabilities

Owner: Product owner / security owner. Severity: Blocking. Status: Open. Confirm the current permission/decision policy including requirements:manage, reviewer assignment and any single-manager exception. Reviewer is a responsibility, not a membership role.

### GAP-009 — Execution evidence and release decision

Owner: Release owner. Severity: Blocking. Status: Open. There are no observed runs, defects, fixes or release decisions in this pack. Obtain real signed/attributable receipts and review every critical criterion before sign-off.

### GAP-010 — Adoption into runtime import schema

Owner: Business analyst / test lead. Severity: Blocking for import. Status: Open. JSON and CSV are reference interchange formats, not a promised direct API payload. Use typed source intake in a disposable approved project, inspect its normalization diff and map IDs before using generated runtime records.