@taodigital/agents 0.0.0-stage → 1.2.1

package/dist/requirements-agent.js

@@ -0,0 +1,641 @@
+"use strict";
+/**
+ * ZeTa-AI Requirements Agent
+ *
+ * Converts product specs (PRDs, user stories, acceptance criteria, release notes)
+ * into structured, testable Requirement objects stored in the Requirements store.
+ *
+ * Each Requirement has:
+ *   - reqId: REQ-{AREA}-{NNN} — stable, sequential per area
+ *   - acceptanceCriteria[]: Given/When/Then deterministic statements
+ *   - priority: CRITICAL | HIGH | MEDIUM | LOW (risk-derived)
+ *   - status: pending (until matchCasesToRequirements() runs)
+ *
+ * Also provides:
+ *   - matchCasesToRequirements(): fuzzy matching of test cases → reqIds
+ *   - generateCoverageGapReport(): Prompt 2 pre-plan gap analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRequirements = extractRequirements;
+exports.generateCoverageGapReport = generateCoverageGapReport;
+exports.buildRequirementsBlock = buildRequirementsBlock;
+const app_brain_1 = require("@taodigital/app-brain");
+const llm_js_1 = require("./llm.js");
+const llm_config_js_1 = require("./llm-config.js");
+const core_1 = require("@taodigital/core");
+// ─── System prompt (Prompt 1 from the spec) ─────────────────────────────────
+const EXTRACTION_SYSTEM = `You are a QA architect converting product specifications into structured, testable requirements.
+
+OUTPUT FORMAT — JSON only, no preamble, no markdown fences:
+{ "requirements": Requirement[] }
+
+Where Requirement = {
+  "reqId": string,           // REQ-{AREA}-{NNN} — e.g. REQ-AUTH-014. Area = 2-5 char uppercase noun from the feature.
+  "title": string,           // Concise, action-oriented. No pronouns.
+  "actor": string | null,    // Who initiates: "user" | "admin" | "system" | "guest" | null
+  "type": string,            // functional | nonfunctional | security | accessibility | data | performance
+  "priority": string,        // CRITICAL | HIGH | MEDIUM | LOW (see rules below)
+  "acceptanceCriteria": string[],  // Given/When/Then strings — at least one per requirement
+  "businessRules": string[], // Thresholds, role limits, constraints not in acceptance criteria
+  "relatedScreenHints": string[], // Screen name nouns/routes (hints only — do not assert they exist)
+  "sourceSection": string | null, // Heading, feature, epic, story, or uploaded-section name from the source input.
+  "derived": boolean         // true if you inferred criterion (not explicitly stated in source)
+}
+
+RULES:
+1. One requirement = one verifiable behaviour. Split compound sentences — never combine two behaviours in one object.
+2. Every requirement MUST have at least one acceptanceCriteria written as deterministic Given/When/Then. If the source lacks one, derive the minimal criterion implied and set derived=true.
+3. Priority assignment:
+   - CRITICAL: auth, authorization, payment, data deletion, PII access, security gates — words "must", "required", "shall"
+   - HIGH: core happy paths, primary CRUD, navigation, data integrity
+   - MEDIUM: secondary flows, validation, edge conditions, warnings
+   - LOW: cosmetic, low-frequency, nice-to-have
+4. No pronouns in title or criteria. No hedging words (possibly, may, might, should probably).
+5. Every acceptanceCriteria string must start with "Given", "When", or "Then" or "And".
+6. reqId must be stable and sequential: REQ-AUTH-001, REQ-AUTH-002, ... per area. Areas derive from the feature noun in the title.
+7. businessRules: only explicit constraints (e.g. "Password must be 8-128 chars", "Max 5 login attempts before lockout").
+8. relatedScreenHints: nouns/routes that hint at screen implementation. Do NOT assert the screen exists.
+9. Preserve the source grouping. If the input has headings, epics, modules, numbered sections, or user-story labels, put the closest group name in sourceSection for every requirement. The CLOSEST means the nearest heading ABOVE that requirement, not the document title. If the document has one top-level title and several sub-sections below it, use the sub-section name (not the top-level title). Example: document title "Title Registration Workflow" with sub-sections "Vehicle Identification", "Fee Calculation", "Owner Validation" → each requirement's sourceSection is the sub-section it came from, NOT "Title Registration Workflow". Different requirements MUST have different sourceSection values if they come from different sections. Never assign the same sourceSection to all requirements unless the document truly has only one section.
+10. Output valid JSON only.
+11. Be EXHAUSTIVE. For a business requirements document (BRD), extract EVERY testable item including:
+    - All business rules with specific numeric constraints (e.g., "Password 3-8 chars" → separate requirement per rule)
+    - All non-functional requirements (performance thresholds, availability, data retention)
+    - All validation rules from tables (field length limits, format constraints, allowed values)
+    - All exception/error scenarios (what happens when X fails)
+    - All integration requirements (external system timeouts, API responses)
+    - Each row in a business rules table = a separate requirement
+    A 40-page BRD should produce 80-150 requirements, not 10.
+12. For business rules tables: each row is a separate requirement. reqId format: REQ-{AREA}-{NNN} where AREA reflects the rule category (AUTH, VIN, FEE, INV, OWN, etc.)`;
+// ─── Prompt 2: coverage gap analysis (pre-plan) ──────────────────────────────
+const GAP_ANALYSIS_SYSTEM = `You are a QA coverage analyst auditing test coverage against requirements.
+
+OUTPUT FORMAT — JSON only:
+{
+  "covered":  [{ "reqId": string, "caseRefs": string[] }],
+  "untested": string[],
+  "unbuilt":  string[],
+  "byPriority": { "CRITICAL": { "covered": N, "total": N }, "HIGH": { ... }, "MEDIUM": { ... }, "LOW": { ... } },
+  "topGaps":  string[]
+}
+
+RULES:
+1. covered: reqId has ≥1 test case whose traceTo == reqId OR whose title/steps clearly satisfy an acceptance criterion. List all matching case refs.
+2. untested: requirement maps to a plausible screen (relatedScreenHints match a crawled screen name) but NO satisfying test case found.
+3. unbuilt: requirement has explicit screen hints, but NONE plausibly match crawled screens. This means "not mapped to crawl", not proof that the app is missing the feature.
+4. topGaps: 5 plain-English gap sentences, highest priority first. Use "not mapped to a crawled screen" instead of "unimplemented" unless the source explicitly says the feature exists and no crawled route can satisfy it.
+5. Never mark covered on weak title-only guess for CRITICAL or SECURITY requirements — require explicit traceTo or criterion-level match.
+6. byPriority: count covered vs total per priority tier.
+7. Output valid JSON only. No preamble.`;
+// ─── Main extraction function ────────────────────────────────────────────────
+async function extractRequirements(opts) {
+    const { tenantId, projectId, sourceText } = opts;
+    if (!sourceText?.trim()) {
+        throw new Error('sourceText is required for requirement extraction.');
+    }
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'testPlan');
+    if (!llmCfg) {
+        throw new Error('LLM provider not configured. Add an AI provider in Workspace → Settings → AI Provider.');
+    }
+    const CHAR_LIMIT = parseInt(process.env.REQUIREMENTS_CHAR_LIMIT ?? '80000', 10);
+    const domainCtx = await (0, llm_config_js_1.getWorkspaceDomainContext)(tenantId, projectId);
+    const sourceSections = detectSourceSections(sourceText);
+    const user = [
+        'Extract structured requirements from the following specification.',
+        'Assign sequential reqIds per area (REQ-AUTH-001, REQ-AUTH-002, REQ-CHECKOUT-001, etc.).',
+        'Preserve source grouping by setting sourceSection from the closest heading, epic, feature, module, story, or numbered section in the input.',
+        sourceSections.length
+            ? `Detected source sections to preserve:\n${sourceSections.map((s) => `- ${s}`).join('\n')}`
+            : '',
+        domainCtx,
+        '',
+        '## Source Document',
+        sourceText.slice(0, CHAR_LIMIT), // cap to avoid context overflow
+    ].filter(Boolean).join('\n');
+    const seed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId}:extract-reqs:${sourceText.slice(0, 3000)}`);
+    const t0 = Date.now();
+    const extractionSystem = await (0, core_1.getAgentPrompt)('requirements-extraction', undefined, tenantId) ?? EXTRACTION_SYSTEM;
+    const { text: raw, usage } = await (0, llm_js_1.askTracked)(extractionSystem, user, llmCfg, undefined, undefined, { temperature: 0, seed });
+    const latencyMs = Date.now() - t0;
+    // Parse JSON
+    const jsonStart = raw.indexOf('{');
+    const jsonEnd = raw.lastIndexOf('}');
+    if (jsonStart === -1 || jsonEnd === -1) {
+        throw new Error('LLM did not return valid JSON for requirement extraction.');
+    }
+    const parsed = JSON.parse(raw.slice(jsonStart, jsonEnd + 1));
+    const rawReqs = parsed.requirements ?? [];
+    const mapRawReqs = (rawList) => rawList.map((r) => ({
+        reqId: String(r.reqId ?? '').toUpperCase(),
+        title: String(r.title ?? ''),
+        actor: r.actor ?? null,
+        type: (['functional', 'nonfunctional', 'security', 'accessibility', 'data', 'performance'].includes(r.type)
+            ? r.type : 'functional'),
+        priority: (['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].includes(r.priority)
+            ? r.priority : 'HIGH'),
+        acceptanceCriteria: Array.isArray(r.acceptanceCriteria) ? r.acceptanceCriteria : [],
+        businessRules: Array.isArray(r.businessRules) ? r.businessRules : [],
+        relatedScreenHints: Array.isArray(r.relatedScreenHints) ? r.relatedScreenHints : [],
+        sourceSection: normalizeSourceSection(r.sourceSection),
+        derived: r.derived === true,
+    })).filter(r => r.reqId && r.title && r.acceptanceCriteria.length > 0);
+    let requirements = mapRawReqs(rawReqs);
+    let droppedCount = rawReqs.length - requirements.length;
+    // Chunked processing for large documents (> CHAR_LIMIT chars)
+    const CHUNK_SIZE = 70000;
+    const CHUNK_OVERLAP = 5000;
+    if (sourceText.length > CHAR_LIMIT) {
+        const chunks = [];
+        let offset = 0;
+        while (offset < sourceText.length) {
+            chunks.push(sourceText.slice(offset, offset + CHUNK_SIZE));
+            offset += CHUNK_SIZE - CHUNK_OVERLAP;
+        }
+        // Skip chunk 0 — already processed above as the first CHAR_LIMIT chars
+        for (let i = 1; i < chunks.length; i++) {
+            const chunkUser = [
+                'Extract structured requirements from the following specification.',
+                'Assign sequential reqIds per area (REQ-AUTH-001, REQ-AUTH-002, REQ-CHECKOUT-001, etc.).',
+                'Preserve source grouping by setting sourceSection from the closest heading, epic, feature, module, story, or numbered section in the input.',
+                sourceSections.length
+                    ? `Detected source sections to preserve:\n${sourceSections.map((s) => `- ${s}`).join('\n')}`
+                    : '',
+                domainCtx,
+                '',
+                '## Source Document',
+                chunks[i],
+            ].filter(Boolean).join('\n');
+            const chunkSeed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId}:extract-reqs-chunk-${i}:${chunks[i].slice(0, 1000)}`);
+            try {
+                const { text: chunkRaw, usage: chunkUsage } = await (0, llm_js_1.askTracked)(extractionSystem, chunkUser, llmCfg, undefined, undefined, { temperature: 0, seed: chunkSeed });
+                const cjStart = chunkRaw.indexOf('{');
+                const cjEnd = chunkRaw.lastIndexOf('}');
+                if (cjStart !== -1 && cjEnd !== -1) {
+                    const chunkParsed = JSON.parse(chunkRaw.slice(cjStart, cjEnd + 1));
+                    const chunkReqs = mapRawReqs(chunkParsed.requirements ?? []);
+                    droppedCount += (chunkParsed.requirements?.length ?? 0) - chunkReqs.length;
+                    requirements = requirements.concat(chunkReqs);
+                }
+                (0, app_brain_1.recordLLMCall)({
+                    tenantId, projectId,
+                    agentType: 'requirements',
+                    label: `requirement_extraction_chunk_${i}`,
+                    entityType: 'requirement',
+                    usage: chunkUsage,
+                    latencyMs: 0,
+                }).catch(console.error);
+            }
+            catch (chunkErr) {
+                console.warn(`[requirements-agent] chunk ${i} extraction failed:`, chunkErr instanceof Error ? chunkErr.message : chunkErr);
+            }
+        }
+        // Deduplicate by reqId: keep first occurrence, but prefer entry with more acceptanceCriteria on collision
+        const seen = new Map();
+        for (const req of requirements) {
+            const existing = seen.get(req.reqId);
+            if (!existing || req.acceptanceCriteria.length > existing.acceptanceCriteria.length) {
+                seen.set(req.reqId, req);
+            }
+        }
+        requirements = [...seen.values()];
+    }
+    (0, app_brain_1.recordLLMCall)({
+        tenantId,
+        projectId,
+        agentType: 'requirements',
+        label: 'requirement_extraction',
+        entityType: 'requirement',
+        usage,
+        latencyMs,
+    }).catch(console.error);
+    const saved = await app_brain_1.AppBrain.upsertRequirements(tenantId, projectId, requirements);
+    if (requirements.length > 0) {
+        await refreshRequirementSkillFiles(tenantId, projectId, requirements);
+    }
+    return { requirements, saved: saved.length, dropped: droppedCount };
+}
+function mdCell(value) {
+    return String(value ?? '')
+        .replace(/\|/g, '\\|')
+        .replace(/\r?\n/g, '<br/>')
+        .trim();
+}
+function criteriaList(value) {
+    return Array.isArray(value) ? value.map((v) => String(v ?? '').trim()).filter(Boolean) : [];
+}
+function requirementHaystack(requirement) {
+    return [
+        requirement.reqId,
+        requirement.title,
+        requirement.actor,
+        requirement.type,
+        requirement.priority,
+        requirement.sourceSection,
+        ...criteriaList(requirement.acceptanceCriteria),
+        ...criteriaList(requirement.businessRules),
+        ...criteriaList(requirement.relatedScreenHints),
+    ].filter(Boolean).join(' ').toLowerCase();
+}
+function requirementMatches(requirement, words) {
+    const text = requirementHaystack(requirement);
+    return words.some((word) => text.includes(word));
+}
+function requirementTable(requirements, emptyMessage) {
+    if (requirements.length === 0)
+        return emptyMessage;
+    return [
+        `| ID | Group | Priority | Type | Title | Criteria |`,
+        `|---|---|---|---|---|---|`,
+        ...requirements.map((r) => {
+            const criteria = criteriaList(r.acceptanceCriteria).map((c) => `- ${mdCell(c)}`).join('<br/>');
+            return `| ${mdCell(r.reqId)} | ${mdCell(r.sourceSection ?? '')} | ${mdCell(r.priority)} | ${mdCell(r.type)} | **${mdCell(r.title)}** | ${criteria} |`;
+        }),
+    ].join('\n');
+}
+async function upsertRequirementSkillFile(tenantId, projectId, kind, content, summary, tags) {
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, kind, content, {
+        summary,
+        tags: ['requirements', 'prd', ...tags],
+        source: 'AUTO',
+    }).catch((e) => console.warn(`[requirements-agent] failed to upsert ${kind} skill file:`, e));
+}
+async function refreshRequirementSkillFiles(tenantId, projectId, requirements) {
+    const byType = (types) => {
+        const set = new Set(types.map((t) => t.toLowerCase()));
+        return requirements.filter((r) => set.has(String(r.type ?? '').toLowerCase()));
+    };
+    const functional = byType(['functional']);
+    const nonfunctional = requirements.filter((r) => ['nonfunctional', 'accessibility', 'data', 'performance'].includes(String(r.type ?? '').toLowerCase()));
+    const security = byType(['security']);
+    const withRules = requirements.filter((r) => criteriaList(r.businessRules).length > 0);
+    const accessibility = byType(['accessibility']);
+    const performance = byType(['performance']);
+    const dataRules = requirements.filter((r) => String(r.type ?? '').toLowerCase() === 'data' || requirementMatches(r, [
+        'data', 'field', 'vin', 'plate', 'inventory', 'expiration', 'date', 'fee', 'amount', 'number', 'code', 'class', 'default', 'value', 'validation',
+    ]));
+    const workflows = requirements.filter((r) => requirementMatches(r, [
+        'workflow', 'flow', 'journey', 'transaction', 'submit', 'submission', 'registration', 'renewal', 'reversal', 'batch', 'queue', 'print', 'order', 'shipment', 'report',
+    ]));
+    const roles = requirements.filter((r) => r.actor || requirementMatches(r, [
+        'role', 'permission', 'operator', 'admin', 'access', 'authorization', 'authorized', 'unauthorized', 'allow', 'deny', 'denied', 'rbac',
+    ]));
+    const integrations = requirements.filter((r) => requirementMatches(r, [
+        'api', 'host', 'dmv', 'external', 'integration', 'transmit', 'transmission', 'response', 'connection', 'secure connection', 'batch', 'webhook',
+    ]));
+    const compliance = requirements.filter((r) => requirementMatches(r, [
+        'compliance', 'agreement', 'audit', 'log', 'retention', 'state agreement', 'privacy', 'pii', 'regulation', 'regulatory', 'vsa', 'security event',
+    ]));
+    await Promise.all([
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS', [
+            '# Product Requirements',
+            '',
+            'Purpose: compact index of all extracted intended behavior. Test generation uses this for traceability only after crawl evidence confirms the UI path exists.',
+            '',
+            requirementTable(requirements, 'No product requirements were extracted.'),
+        ].join('\n'), 'Structured product requirements extracted from uploaded specifications.', ['index', 'traceability']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_FUNCTIONAL', [
+            '# Functional Requirements',
+            '',
+            'Purpose: user-visible behaviors, workflows, permissions, and form rules that may become executable UI tests when matched to crawled evidence.',
+            '',
+            requirementTable(functional, 'No functional requirements were extracted.'),
+        ].join('\n'), 'Functional requirements that can drive executable UI and flow test generation.', ['functional', 'ui-tests']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_NONFUNCTIONAL', [
+            '# Nonfunctional Requirements',
+            '',
+            'Purpose: quality attributes such as accessibility, data, performance, reliability, and compliance that influence specialized test passes.',
+            '',
+            requirementTable(nonfunctional, 'No nonfunctional requirements were extracted.'),
+        ].join('\n'), 'Nonfunctional requirements for specialized quality and compliance passes.', ['nonfunctional', 'quality']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_SECURITY', [
+            '# Security Requirements',
+            '',
+            'Purpose: authorization, authentication, privacy, audit, and abuse-prevention expectations used by security and negative test passes.',
+            '',
+            requirementTable(security, 'No security requirements were extracted.'),
+        ].join('\n'), 'Security-focused requirements used by authorization and negative test generation.', ['security', 'authorization']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_BUSINESS_RULES', [
+            '# Business Rules',
+            '',
+            'Purpose: constraints, thresholds, role rules, dates, and validation limits that should appear in assertions and edge tests.',
+            '',
+            withRules.length
+                ? withRules.map((r) => [
+                    `## ${r.reqId}: ${r.title}`,
+                    `Priority: ${r.priority} | Type: ${r.type} | Group: ${r.sourceSection ?? 'General'}`,
+                    ...criteriaList(r.businessRules).map((rule) => `- ${rule}`),
+                ].join('\n')).join('\n\n')
+                : 'No explicit business rules were extracted.',
+        ].join('\n'), 'Business rules extracted from requirements for assertions, boundaries, and edge cases.', ['business-rules', 'assertions']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_ACCEPTANCE_CRITERIA', [
+            '# Acceptance Criteria',
+            '',
+            'Purpose: Given/When/Then expectations used to shape expected results without inventing missing UI steps.',
+            '',
+            requirements.map((r) => [
+                `## ${r.reqId}: ${r.title}`,
+                ...criteriaList(r.acceptanceCriteria).map((criterion) => `- ${criterion}`),
+            ].join('\n')).join('\n\n'),
+        ].join('\n'), 'Acceptance criteria normalized for expected-result generation.', ['acceptance-criteria', 'expected-results']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_TRACEABILITY', [
+            '# Requirement Traceability Hints',
+            '',
+            'Purpose: source sections and screen hints used to compare uploaded intent with crawled implementation evidence.',
+            '',
+            `| ID | Group | Screen Hints | Derived |`,
+            `|---|---|---|---|`,
+            ...requirements.map((r) => `| ${mdCell(r.reqId)} | ${mdCell(r.sourceSection ?? '')} | ${mdCell(criteriaList(r.relatedScreenHints).join(', '))} | ${r.derived ? 'yes' : 'no'} |`),
+        ].join('\n'), 'Source-section and screen-hint map used for truth comparison and coverage review.', ['traceability', 'truth-diff']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_WORKFLOWS', [
+            '# Requirement Workflows',
+            '',
+            'Purpose: end-to-end flows, transaction lifecycles, queues, batch jobs, printing, ordering, and operational journeys used by E2E and state-transition passes.',
+            '',
+            requirementTable(workflows, 'No workflow-oriented requirements were extracted.'),
+        ].join('\n'), 'Workflow and lifecycle requirements used for E2E, state-transition, and operational test generation.', ['workflows', 'e2e', 'state-transition']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_ROLES_PERMISSIONS', [
+            '# Roles And Permissions Requirements',
+            '',
+            'Purpose: actors, roles, permission gates, access restrictions, and authorization outcomes used by RBAC and negative/security test passes.',
+            '',
+            requirementTable(roles, 'No role or permission requirements were extracted.'),
+        ].join('\n'), 'Role, actor, and permission requirements used for RBAC and authorization testing.', ['roles', 'permissions', 'rbac']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_DATA_RULES', [
+            '# Data And Validation Rules',
+            '',
+            'Purpose: field constraints, identifiers, inventory values, dates, fees, defaults, and validation rules used by data, edge, and boundary-value tests.',
+            '',
+            requirementTable(dataRules, 'No data or validation requirements were extracted.'),
+        ].join('\n'), 'Data rules and validation constraints for boundary, edge, and data-driven tests.', ['data', 'validation', 'boundary-values']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_INTEGRATIONS', [
+            '# Integration Requirements',
+            '',
+            'Purpose: external systems, host communication, transmissions, API behavior, response handling, and batch/integration contracts used by API and integration tests.',
+            '',
+            requirementTable(integrations, 'No integration requirements were extracted.'),
+        ].join('\n'), 'Integration and external-system requirements for API, batch, and host-communication tests.', ['integrations', 'api', 'external-systems']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_COMPLIANCE_AUDIT', [
+            '# Compliance And Audit Requirements',
+            '',
+            'Purpose: agreements, audit logs, compliance gates, privacy/security evidence, and regulatory obligations used by audit and governance tests.',
+            '',
+            requirementTable(compliance, 'No compliance or audit requirements were extracted.'),
+        ].join('\n'), 'Compliance, agreement, audit, and regulatory requirements for governance-focused tests.', ['compliance', 'audit', 'governance']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_ACCESSIBILITY', [
+            '# Accessibility Requirements',
+            '',
+            'Purpose: explicit accessibility expectations from requirements used by WCAG and assistive-technology test passes.',
+            '',
+            requirementTable(accessibility, 'No accessibility requirements were extracted.'),
+        ].join('\n'), 'Accessibility requirements for WCAG and assistive-technology test generation.', ['accessibility', 'wcag', 'a11y']),
+        upsertRequirementSkillFile(tenantId, projectId, 'REQUIREMENTS_PERFORMANCE', [
+            '# Performance Requirements',
+            '',
+            'Purpose: timing, batch, responsiveness, stability, and load expectations used by performance and load-oriented passes.',
+            '',
+            requirementTable(performance, 'No performance requirements were extracted.'),
+        ].join('\n'), 'Performance and load expectations extracted from requirement documents.', ['performance', 'load', 'sla']),
+    ]);
+}
+function detectSourceSections(sourceText) {
+    const sections = [];
+    const seen = new Set();
+    const lines = sourceText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    for (const line of lines) {
+        const cleaned = line
+            .replace(/^#{1,6}\s+/, '')
+            .replace(/^\d+(?:\.\d+)*[\).:-]?\s+/, '')
+            .replace(/^[-*]\s+/, '')
+            .trim();
+        const isLikelyHeading = /^#{1,6}\s+/.test(line) ||
+            /^(feature|module|epic|story|user story|section|requirement group|screen|page|flow)\s*[:\-]/i.test(line) ||
+            // Allow parens and dots in heading text (e.g. "Title Registration (1 Step) Workflow")
+            (/^[A-Z][A-Za-z0-9 &/_().:-]{2,80}$/.test(cleaned) && cleaned.split(/\s+/).length <= 10 && !/[!?]$/.test(cleaned) && cleaned.split(/\s+/).length >= 2);
+        if (!isLikelyHeading || cleaned.length < 3 || cleaned.length > 100)
+            continue;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        sections.push(cleaned);
+        if (sections.length >= 50)
+            break;
+    }
+    return sections;
+}
+function normalizeSourceSection(value) {
+    const section = String(value ?? '').trim();
+    if (!section || section.toLowerCase() === 'null' || section.toLowerCase() === 'undefined')
+        return null;
+    return section.slice(0, 120);
+}
+// ─── Coverage gap analysis (Prompt 2) ───────────────────────────────────────
+async function generateCoverageGapReport(opts) {
+    const { tenantId, projectId } = opts;
+    const [requirements, testCases, screens] = await Promise.all([
+        app_brain_1.AppBrain.listRequirements(tenantId, projectId),
+        app_brain_1.AppBrain.listTestCases(tenantId, projectId, { status: 'APPROVED' }),
+        app_brain_1.AppBrain.getProjectMap(tenantId, projectId).then(pm => (pm?.screens ?? []).map((s) => s.name)),
+    ]);
+    if (requirements.length === 0) {
+        return { covered: [], untested: [], unbuilt: [], byPriority: {}, topGaps: ['No requirements extracted yet. Upload a PRD or user stories first.'] };
+    }
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'testPlan');
+    if (!llmCfg) {
+        // Fallback: do simple traceTo matching without LLM
+        return await matchWithoutLLM(requirements, testCases, screens);
+    }
+    const requirementsSummary = requirements.map((r) => ({
+        reqId: r.reqId,
+        title: r.title,
+        priority: r.priority,
+        type: r.type,
+        relatedScreenHints: r.relatedScreenHints,
+        acceptanceCriteria: r.acceptanceCriteria.slice(0, 2), // first 2 criteria only
+    }));
+    const casesSummary = testCases.map((tc) => ({
+        ref: tc.ref,
+        title: tc.title,
+        traceTo: tc.traceTo,
+        groundedOn: tc.groundedOn.slice(0, 3),
+        kind: tc.kind,
+        priority: tc.priority,
+    }));
+    const user = [
+        `REQUIREMENTS (${requirements.length} total):`,
+        JSON.stringify(requirementsSummary, null, 2).slice(0, 6000),
+        '',
+        `TEST CASES (${testCases.length} approved):`,
+        JSON.stringify(casesSummary, null, 2).slice(0, 4000),
+        '',
+        `CRAWLED SCREENS: ${screens.join(', ')}`,
+    ].join('\n');
+    try {
+        const gapSeed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId}:coverage-gap:${requirements.map((r) => r.reqId).sort().join('|').slice(0, 300)}`);
+        const t0 = Date.now();
+        const gapSystem = await (0, core_1.getAgentPrompt)('requirements-gap-analysis', undefined, tenantId) ?? GAP_ANALYSIS_SYSTEM;
+        const { text: raw, usage } = await (0, llm_js_1.askTracked)(gapSystem, user, llmCfg, undefined, undefined, { temperature: 0, seed: gapSeed });
+        const latencyMs = Date.now() - t0;
+        const jsonStart = raw.indexOf('{');
+        const jsonEnd = raw.lastIndexOf('}');
+        const result = await normalizeCoverageResult(JSON.parse(raw.slice(jsonStart, jsonEnd + 1)), requirements, screens);
+        (0, app_brain_1.recordLLMCall)({
+            tenantId, projectId,
+            agentType: 'requirements',
+            label: 'coverage_gap_analysis',
+            entityType: 'requirement',
+            usage, latencyMs,
+        }).catch(console.error);
+        // Persist coverage status back to requirements
+        await app_brain_1.AppBrain.updateRequirementStatuses(tenantId, projectId, {
+            covered: result.covered.map(c => c.reqId),
+            untested: result.untested,
+            unbuilt: result.unbuilt,
+        });
+        return result;
+    }
+    catch (err) {
+        console.error('[requirements-agent] gap analysis LLM failed:', err instanceof Error ? err.message : err);
+        return await matchWithoutLLM(requirements, testCases, screens);
+    }
+}
+// ─── Deterministic fallback (no LLM) ────────────────────────────────────────
+function normalizeForMatch(s) {
+    return String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+function requirementMatchesScreen(req, screens) {
+    const screenText = screens.map(normalizeForMatch).join(' ');
+    if (!screenText)
+        return false;
+    const hints = Array.isArray(req.relatedScreenHints) ? req.relatedScreenHints : [];
+    if (hints.some((h) => {
+        const n = normalizeForMatch(h);
+        return n && screenText.includes(n);
+    }))
+        return true;
+    const stop = new Set(['the', 'a', 'an', 'to', 'and', 'or', 'for', 'with', 'can', 'be', 'is', 'are', 'user', 'system', 'requirement']);
+    const tokens = normalizeForMatch(req.title)
+        .split(/\s+/)
+        .filter((t) => t.length >= 4 && !stop.has(t));
+    return tokens.some((t) => screenText.includes(t));
+}
+/**
+ * Pre-compute semantic screen matches for all requirements in one pass.
+ * Returns a Set of reqIds where at least one screen is semantically relevant.
+ * Falls back gracefully if reranker is unavailable.
+ */
+async function buildSemanticScreenMatchSet(requirements, screens) {
+    if (screens.length === 0)
+        return new Set();
+    const matched = new Set();
+    try {
+        await Promise.all(requirements.map(async (req) => {
+            const hints = Array.isArray(req.relatedScreenHints) ? req.relatedScreenHints.filter(Boolean) : [];
+            const query = [req.title, ...hints].join(' ');
+            const ranked = await (0, app_brain_1.rerankStrings)(query, screens, 1, 0);
+            if (ranked[0] && ranked[0].score >= 0.55)
+                matched.add(req.reqId);
+        }));
+    }
+    catch {
+        // reranker unavailable — return empty set (caller falls back to sync check)
+    }
+    return matched;
+}
+function priorityRank(p) {
+    return { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 }[p] ?? 9;
+}
+async function normalizeCoverageResult(result, requirements, screens) {
+    const coveredIds = new Set((result.covered ?? []).map((c) => c.reqId));
+    const untested = new Set(result.untested ?? []);
+    const unbuilt = new Set(result.unbuilt ?? []);
+    const semanticMatches = await buildSemanticScreenMatchSet(requirements, screens);
+    for (const req of requirements) {
+        if (coveredIds.has(req.reqId)) {
+            untested.delete(req.reqId);
+            unbuilt.delete(req.reqId);
+            continue;
+        }
+        const hints = Array.isArray(req.relatedScreenHints) ? req.relatedScreenHints.filter(Boolean) : [];
+        const hasScreenMatch = requirementMatchesScreen(req, screens) || semanticMatches.has(req.reqId);
+        if (unbuilt.has(req.reqId) && (hints.length === 0 || hasScreenMatch)) {
+            unbuilt.delete(req.reqId);
+            untested.add(req.reqId);
+        }
+    }
+    const byPriority = {};
+    for (const req of requirements) {
+        const p = req.priority;
+        if (!byPriority[p])
+            byPriority[p] = { covered: 0, total: 0 };
+        byPriority[p].total++;
+        if (coveredIds.has(req.reqId))
+            byPriority[p].covered++;
+    }
+    const topGaps = [...new Set([...unbuilt, ...untested])]
+        .map((reqId) => requirements.find((r) => r.reqId === reqId))
+        .filter(Boolean)
+        .sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority))
+        .slice(0, 5)
+        .map((r) => {
+        if (unbuilt.has(r.reqId)) {
+            return `${r.priority}: Requirement ${r.reqId} is not mapped to any crawled screen; add screen hints or crawl the relevant route before coverage can be verified.`;
+        }
+        return `${r.priority}: Requirement ${r.reqId} has no approved test case linked by traceTo or matching acceptance criteria.`;
+    });
+    return {
+        covered: result.covered ?? [],
+        untested: [...untested],
+        unbuilt: [...unbuilt],
+        byPriority,
+        topGaps,
+    };
+}
+async function matchWithoutLLM(requirements, testCases, screens = []) {
+    const covered = [];
+    const untested = [];
+    const unbuilt = [];
+    const byPriority = {};
+    const semanticMatches = await buildSemanticScreenMatchSet(requirements, screens);
+    for (const req of requirements) {
+        const p = req.priority;
+        if (!byPriority[p])
+            byPriority[p] = { covered: 0, total: 0 };
+        byPriority[p].total++;
+        // Match by traceTo exact match
+        const matching = testCases.filter((tc) => tc.traceTo === req.reqId);
+        if (matching.length > 0) {
+            covered.push({ reqId: req.reqId, caseRefs: matching.map((tc) => tc.ref ?? tc.id) });
+            byPriority[p].covered++;
+        }
+        else if (requirementMatchesScreen(req, screens) || semanticMatches.has(req.reqId) || !req.relatedScreenHints?.length) {
+            untested.push(req.reqId);
+        }
+        else {
+            unbuilt.push(req.reqId);
+        }
+    }
+    const topGaps = [...unbuilt, ...untested]
+        .map(reqId => requirements.find(r => r.reqId === reqId))
+        .filter(Boolean)
+        .sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority))
+        .slice(0, 5)
+        .map((r) => unbuilt.includes(r.reqId)
+        ? `${r.priority}: Requirement ${r.reqId} is not mapped to any crawled screen; add screen hints or crawl the relevant route before coverage can be verified.`
+        : `${r.priority}: Requirement ${r.reqId} has no approved test case linked by traceTo or matching acceptance criteria.`);
+    return { covered, untested, unbuilt, byPriority, topGaps };
+}
+// ─── Requirement summary block for LLM injection ────────────────────────────
+/**
+ * Build a compact requirements block to inject into test generation prompts.
+ * Used by test-case-agent.ts to populate traceTo with real reqIds.
+ */
+function buildRequirementsBlock(requirements) {
+    if (!requirements.length)
+        return '';
+    const lines = requirements.slice(0, 30).map((r) => `  ${r.reqId} [${r.priority}] ${r.title}${r.relatedScreenHints?.length ? ` (hints: ${r.relatedScreenHints.join(', ')})` : ''}`);
+    return [
+        'REQUIREMENTS (use reqId for traceTo when this test case satisfies an acceptance criterion):',
+        ...lines,
+        requirements.length > 30 ? `  ... and ${requirements.length - 30} more` : '',
+    ].filter(Boolean).join('\n');
+}

package/dist/scenario-agent.d.ts

@@ -0,0 +1,20 @@
+export interface ScenarioOutput {
+    title: string;
+    description?: string;
+    gherkin: string;
+}
+export declare function generateScenarios(opts: {
+    tenantId: string;
+    projectId: string;
+    requirement: {
+        reqId: string;
+        title: string;
+        actor?: string;
+        type?: string;
+        priority?: string;
+        acceptanceCriteria?: string[];
+        businessRules?: string[];
+    };
+    /** Number of scenarios to generate. Default 4, min 1, max 10. */
+    count?: number;
+}): Promise<ScenarioOutput[]>;