@reportforge/playwright-pdf 0.21.0 → 0.22.1

package/README.md

@@ -57,14 +57,15 @@ Three templates, one reporter. Every PDF is fully offline: fonts, charts, and sc
 - **Shard merging**: combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
 - **Notifications**: post pass/fail summaries to Slack, Teams, Discord, or email after each run; configurable trigger (`always` / `failure` / `success`) per channel; email and Discord support optional PDF attachment via `attachPdf`
 - **Flakiness trend**: top-N flakiest tests table with per-test dot sparkline across stored history runs in the `detailed` template; `flakinessTopN` option (default 5, `0` disables)
-- **Offline failure analysis**: sorts each failure into one of 7 root-cause buckets and renders a root-cause chip under each failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service: a small embedded classifier that updates over your existing license refresh; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
-- **On-device training**: teach the classifier your team's failures without any data leaving your machine. Label locally-collected samples (`npx @reportforge/playwright-pdf label-feedback`), then `train-model` trains and cross-validates a personal layer on-device; it activates only when it measurably beats the base model on your own labeled set (`evaluate-model` shows the comparison any time). Commit the model file to your repo via `failureAnalysis.localModelPath` to share it with CI. Training data, the trained model, and evaluation are all local files; the analysis code cannot even name a network primitive (CI-enforced source scan).
+- **Pass-rate trend**: cross-run trend chart from stored history; opt-in `remoteHistory` keeps the trend alive on ephemeral CI runners by storing aggregate numbers only (pass rate, counts, duration, verdict; no test titles or error text, and the branch name never travels in plaintext), with no extra network calls
+- **Offline failure analysis**: sorts each failure into one of 7 root-cause buckets and renders a root-cause chip under each failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service: a small embedded classifier with automatic updates; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
+- **On-device training**: teach the classifier your team's failures without any data leaving your machine. Label locally-collected samples (`npx @reportforge/playwright-pdf label-feedback`), then `train-model` trains and cross-validates a personal layer on-device; it activates only when it measurably beats the base model on your own labeled set (`evaluate-model` shows the comparison any time). Commit the model file to your repo via `failureAnalysis.localModelPath` to share it with CI. Training data, the trained model, and evaluation are all local files; the analysis code cannot even name a network primitive (enforced by an automated source audit).
 - `npx @reportforge/playwright-pdf export-feedback`: merges your locally-collected feedback (tokenized + redacted) into one CSV for review or moving between machines. Local file only; there is no upload.
 - **Rich execution capture**: opt-in "Steps to Reproduce" outline (a nested, copy-pasteable Markdown list of your `test.step`s and assertions; add `apiSteps` for the full click/fill/check trail), Node console tail, and trace/video links under each failed test in the defect log. Read straight from the Playwright step tree: no fixtures, no test-code changes. Enable via `capture` (`steps` / `apiSteps` / `console` / `evidence`); off by default.
 - **Configurable sections**: add or remove any report section per template via `sections`.
 - **Executive report brief band**: leads with a plain-language brief (trend + root causes) and one hero pass-rate number instead of a flat KPI grid
-- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
-- **Update notice**: when a newer reporter version is published, each run ends with one info line naming it and the update command; delivered over the existing license refresh, no extra network calls
+- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a locally cached license between refreshes
+- **Update notice**: when a newer reporter version is published, each run ends with one info line naming it and the update command; no extra network calls
 
 ---
 
@@ -107,14 +108,14 @@ npx playwright test
 
 ### Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 20
 - `@playwright/test` ≥ 1.40 (peer dependency)
-- `puppeteer-core` ≥ 21 (peer dependency)
+- `puppeteer-core` ≥ 21 < 26 (peer dependency)
 - Chrome or Chromium installed on the machine
 
 ### Chrome setup
 
-The reporter auto-detects Chrome via `PUPPETEER_EXECUTABLE_PATH`, then system Chrome, then `chrome-finder`. Full per-OS instructions: [reportforge.org/docs/running-tests#chrome-setup](https://reportforge.org/docs/running-tests#chrome-setup).
+The reporter locates Chrome via the `puppeteerExecutablePath` option first, then the `PUPPETEER_EXECUTABLE_PATH` environment variable, then `chrome-finder` (system Chrome), then puppeteer-core's bundled Chromium if present. Full per-OS instructions: [reportforge.org/docs/running-tests#chrome-setup](https://reportforge.org/docs/running-tests#chrome-setup).
 
 **Windows**
 
@@ -199,15 +200,16 @@ All options are the second element of the reporter tuple.
 | `maxFileSizeMb` | `number` | `8` | Soft cap on the final PDF size in MB. If exceeded, the report is re-rendered once with the `'max'` compression preset. |
 | `shardResults` | `string \| string[]` | n/a | Glob or path array of Playwright JSON shard report files to merge into one PDF. See the Shard Merging docs. |
 | `notify` | `object` | n/a | Notification channels: `slack`, `teams` (each `{ url, enabled, on }`), `discord` (`{ url, enabled, on, attachPdf }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications docs. |
-| `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded Naive Bayes; no runtime network) with on-device personalization: label collected failures, then the `train-model` CLI trains + evaluates a local layer entirely on your machine; it activates only when it beats the base model, and nothing leaves the machine. Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `collectScope` (`blind-spots`\|`all`, default `blind-spots`), `autoUpdateModel` (default `true`), `localModel` (use the gate-passed on-device model, default `true`), `localModelPath` (share a team-trained model via a repo-committed file). See the Failure Analysis docs. |
+| `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded classifier; no runtime network) with on-device personalization: label collected failures, then the `train-model` CLI trains + evaluates a local layer entirely on your machine; it activates only when it beats the base model, and nothing leaves the machine. Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `collectScope` (`blind-spots`\|`all`, default `blind-spots`), `autoUpdateModel` (default `true`), `localModel` (use the gate-passed on-device model, default `true`), `localModelPath` (share a team-trained model via a repo-committed file). See the Failure Analysis docs. |
 | `capture` | `object` | `{}` (off) | Opt-in rich execution capture for the defect log (reporter-side; no fixtures, no test-code changes). Fields: `steps` (a copy-pasteable "Steps to Reproduce" outline built from the Playwright step tree; each row is a Markdown list line indented under its parent `test.step`, default `false`), `apiSteps` (include every top-level `pw:api` action (click/fill/check/goto) in the outline for a full action trail; without it the outline shows only `test.step` intent + `expect` assertions, default `false`), `console` (Node stdout/stderr tail, default `false`), `evidence` (trace/video file links, default `false`), `maxSteps` (default `50`), `maxConsoleLines` (default `50`). Renders in the Defect Log section of the `detailed` template. |
 | `live` | `object` | `{}` (off) | Opt-in live test-execution streaming. When `enabled`, the reporter prints an unguessable watch link to the CI logs at run start and streams per-test progress to the hosted dashboard while tests run; all shards of one CI run converge on a single live view. Fields: `enabled` (default `false`), `runId` (override the auto-derived run id), `serverUrl` (override the streaming server), `steps` (`none`\|`failed`\|`intent`\|`all`, default `failed`; `intent` shows only your `test.step` names plus any failing step), `console` (stream stdout/stderr tails, default `false`), `flushMs` (batch debounce 500-10000, default `2000`). The PDF at the end of the run is unaffected. Requires an active subscription with the `live` entitlement. See the Live Runs docs. |
 | `historyFile` | `string` | `~/.reportforge/{key}/history.json` | Path to the history JSON file. Relative paths resolve from `cwd`. Enables pass-rate trending charts in the `detailed` template. |
 | `historySize` | `number` | `10` | Maximum number of test runs to keep in the history file (integer ≥ 2). Older runs are pruned on append. |
 | `showTrend` | `boolean` | `true` | Show the pass-rate sparkline and delta badge in the `detailed` template. Set to `false` to disable history tracking entirely. |
-| `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One request per run over the existing license connection carrying aggregate numbers only — no test titles, no error text; the branch name is sent as a hash. Falls back to the local history file on any failure. See the History docs. |
+| `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One small authenticated request per run carrying aggregate numbers only — no test titles, no error text, and the branch name never travels in plaintext. Falls back to the local history file on any failure. See the History docs. |
 | `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
 | `slowTestThreshold` | `number` | `10` | Minimum timed-test count before `SLOW` badges appear in the suite breakdown: below this, every test is trivially the "slowest" so badges stay hidden. On larger runs only genuine outliers (at least 2× the median test duration) are badged, so the badge stays rare. Set to `0` to drop the run-size gate (outliers still required). |
+| `requirementTagPattern` | `string` | `'^@?[A-Z][A-Z0-9]*-\\d+$'` | Regex deciding which tags count as requirement IDs in the Requirements Traceability section (`detailed` template). Matching tags (ticket shapes like `@ODP-5328`, `REQ-001`) get the traceability matrix; everything else (`@regression`, `@sanity`) collapses into a compact tag summary instead of repeating identical rows. Set to `''` to disable the split and list every tag in the matrix. |
 | `templatePath` | `string \| string[]` | n/a | Path to a custom Handlebars (`.hbs`) template file. Takes precedence over `template`. Pass an array to generate one PDF per custom template. See the Custom Templates docs. |
 | `sections` | `object` | per-template | Override which report sections appear, on top of the chosen template's defaults. Flat keys are the baseline for every chosen template; per-template keys (`minimal`\|`detailed`\|`executive`) override per template. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. See the Report Sections docs. |
 <!-- AUTOGEN:options-table END -->
@@ -237,7 +239,7 @@ reporter: [
 
 `steps: 'intent'` shows only your `test.step` names (plus any failing step): the cleanest, most readable trail. `'all'` adds every action and assertion beneath its parent step; `'failed'` (default) keeps intent + assertions + failures.
 
-Sharded runs need no extra config: the run id is derived from the run-shared CI identifier (e.g. `GITHUB_RUN_ID`), identical across every matrix shard. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
+Sharded runs need no extra config: every shard of one CI run converges on the same live view automatically. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
 
 Live streaming is best-effort and entitlement-gated: if the server is unreachable the run is unaffected, and an active subscription with the `live` feature is required. If you've configured Slack/Teams/Discord notifications, the watch link is also posted to those channels when the run starts.
 
@@ -329,7 +331,7 @@ reporter: [['@reportforge/playwright-pdf', {
 }]]
 ```
 
-One request per run over the existing license connection, carrying aggregate numbers only (pass rate, counts, duration, verdict; no test titles, no error text — the branch name is sent as a hash). The server keeps the last 100 runs per project + branch and returns them for the chart; any failure falls back to the local file. The flakiness table stays local-only by design (it needs test titles, which never leave your machine). Bitbucket Pipelines users especially: Bitbucket caches are immutable once written, so `remoteHistory` is the practical path there.
+One small authenticated request per run, carrying aggregate numbers only (pass rate, counts, duration, verdict; no test titles, no error text, and the branch name never travels in plaintext). The server keeps roughly the last 100 runs per project + branch, expiring after 180 days, and returns them for the chart; any failure falls back to the local file. The flakiness table stays local-only by design (it needs test titles, which never leave your machine). Bitbucket Pipelines users especially: Bitbucket caches are immutable once written, so `remoteHistory` is the practical path there.
 
 **CI caching alternative** (keeps even aggregate numbers off the server): set `historyFile` to a project-relative path and cache it between runs:
 
@@ -438,17 +440,18 @@ reporter: [['@reportforge/playwright-pdf', {
 |---|---|
 | `coverPage` | Full-page cover: title, verdict badge, KPI stats strip, branch + commit |
 | `analysisOneliner` | One-line failure-analysis summary banner |
-| `releaseGate` | Ship/hold recommendation banner (APPROVED TO SHIP / HOLD) |
+| `releaseGate` | Ship/hold recommendation banner (APPROVED TO SHIP / HOLD, or a neutral NO TESTS RAN when the run executed zero tests) |
 | `summary` | KPI strip (total · passed · failed · timed-out · skipped · flaky), verdict, duration, pass rate, flaky callout |
 | `charts` | Pass-rate doughnut + stacked suite-results bar |
 | `trend` | Pass-rate trend line, run-history table, and flakiness table (rendered inside `charts`) |
-| `requirementsMatrix` | Tests grouped by `@tag('REQ-…')` with coverage bars (requirements traceability) |
+| `requirementsMatrix` | Requirement-ID tags as a traceability matrix with pass-rate bars, plus a category tag summary |
 | `ciEnvironment` | Branch, commit, browsers, CI provider, OS, Node, Playwright, projects, workers |
 | `suiteBreakdown` | Per-suite → per-test table (status, duration, tags, retries). Failed tests carry their failure detail, root-cause chip, and a `SLOW` badge inline (the three keys below) |
 | `failureDeepDive` | Inline failure detail under each failed test in the breakdown: error message, stack trace, screenshot, retry history |
 | `failureAnalysis` | Inline per-test root-cause chip under each failed test (category + representative error + match strength, from the offline classifier) |
 | `slowTests` | `SLOW` badge on the duration-ranked slowest tests, shown inline in the breakdown |
 | `defectLog` | `DEF-####` numbered failure table (severity, duration) + opt-in repro detail (`capture`) |
+| `briefBand` | Executive brief band: one plain-language sentence (trend delta + root causes) and a hero pass-rate stat |
 
 #### Display modifiers: tune a section that's on
 
@@ -467,7 +470,7 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 | Section | minimal | detailed | executive |
 |---|:-:|:-:|:-:|
 | `coverPage` | – | – | ✓ |
-| `analysisOneliner` | – | – | ✓ |
+| `analysisOneliner` | – | – | – |
 | `releaseGate` | ✓ | ✓ | ✓ |
 | `summary` | ✓ | ✓ | ✓ |
 | `charts` | – | ✓ | ✓ |
@@ -479,6 +482,7 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 | `failureAnalysis` | – | ✓ | – |
 | `slowTests` | – | ✓ | ✓ |
 | `defectLog` | – | ✓ | – |
+| `briefBand` | – | – | ✓ |
 | `passRate` | ✓ | ✓ | ✓ |
 | `fullEnvironment` | – | ✓ | – |
 | `retries` | ✓ | ✓ | – |
@@ -621,10 +625,10 @@ stage('Playwright Tests') {
 ReportForge ships a **hybrid offline-first** model:
 
 1. Paste your `RFSU-…` key into the config once (or set `RF_LICENSE_KEY`).
-2. On first run the reporter activates against the license server, receives a short-lived **Ed25519-signed JWT**, and caches it at `~/.reportforge/license.json`.
-3. Every subsequent run is **fully offline**: the cached JWT is verified locally against a public key bundled into the npm package. No network call.
-4. When the cache has less than 24 hours left, the reporter refreshes it in the background.
-5. Each subscription allows up to **25 active machines** in any rolling 30-day window. Machines that haven't run in 30 days are pruned automatically.
+2. On first run the reporter activates against the license server and caches a signed license at `~/.reportforge/license.json`.
+3. Every subsequent run is **fully offline**: the cached license is validated on-device. No network call.
+4. The reporter refreshes the cache automatically in the background before it expires.
+5. Each subscription allows up to **25 active machines**. Machines that haven't run in 30 days free up automatically.
 
 Cancel the subscription and the reporter keeps working until the end of the current billing period, then stops generating PDFs until you restart. **A license issue never aborts your test run**: the reporter logs a warning and skips PDF generation; your Playwright tests still pass.
 
@@ -639,14 +643,14 @@ Full lifecycle + offline failure modes: [reportforge.org/docs/licensing](https:/
 
 ## Requirements Traceability
 
-The `detailed` template generates a requirements matrix from test tags. Tag tests to link them to requirements:
+The `detailed` template generates a requirements matrix from test tags. Tag tests with ticket-shaped IDs to link them to requirements:
 
 ```ts
-test('@REQ-101 user can login', async ({ page }) => { /* ... */ });
-test.describe('@FEAT-payment', () => { /* ... */ });
+test('user can login', { tag: ['@REQ-101', '@smoke'] }, async ({ page }) => { /* ... */ });
+test.describe('payment', { tag: '@PAY-204' }, () => { /* ... */ });
 ```
 
-The matrix rolls tests up per tag with pass count, fail count, and coverage percentage.
+Tags matching `requirementTagPattern` (default: ticket shapes like `@REQ-101`, `@ODP-5328`, `JIRA-42`) each get a matrix row — test count, pass/fail counts, and a pass-rate bar — sorted by ID. Category tags (`@smoke`, `@regression`) collapse into a compact tag summary below the matrix instead of repeating one near-identical row per tag. Set `requirementTagPattern: ''` to disable the split and list every tag in the matrix.
 
 ---
 
@@ -675,7 +679,7 @@ Common issues:
 - **`Chrome/Chromium not found`** → install Google Chrome Stable; don't use the Ubuntu `chromium-browser` snap.
 - **Charts blank** → ensure `npm run bundle-chartjs` ran at build; the reporter waits up to 30s for `window.__chartsReady`.
 - **`pdfPassword` ignored** → requires `qpdf` on `PATH` (`apt install qpdf` / `brew install qpdf` / `choco install qpdf`).
-- **No PDF generated** → verify `RF_LICENSE_KEY` is set and your subscription is active. `RF_DEBUG=1` will show the activation result; missing key, expired subscription, network failure, or no JWT cache all skip PDF generation.
+- **No PDF generated** → verify `RF_LICENSE_KEY` is set and your subscription is active. `RF_DEBUG=1` will show the activation result; missing key, expired subscription, network failure, or no license cache all skip PDF generation.
 
 Full guide: [reportforge.org/docs/troubleshooting](https://reportforge.org/docs/troubleshooting).
 
@@ -693,7 +697,7 @@ Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
 - [Templates](https://reportforge.org/docs/templates): minimal, detailed, executive
 - [Live runs](https://reportforge.org/docs/advanced/live): stream per-test progress to a shared watch link
 - [Report Sections](https://reportforge.org/docs/configuration#report-sections): add or remove sections per template
-- [License & offline behaviour](https://reportforge.org/docs/licensing): JWT cache, machine cap, cancellation
+- [License & offline behaviour](https://reportforge.org/docs/licensing): license cache, machine cap, cancellation
 - [Troubleshooting](https://reportforge.org/docs/troubleshooting): common issues and debug flags
 - [Changelog](https://reportforge.org/changelog): version history and release notes
 

package/SECURITY.md

@@ -40,8 +40,8 @@ Out of scope:
 
 - Denial of service / volumetric attacks.
 - Reports about the 25-machine licensing cap working as documented.
-- Vulnerabilities exclusively in third-party services we integrate
-  (Razorpay, Clerk, Vercel, Resend) — report those upstream.
+- Vulnerabilities exclusively in third-party services we integrate (for
+  example our payment provider, Razorpay) — report those upstream.
 
 ## Supported versions
 

package/dist/cli/index.js

@@ -95,7 +95,7 @@ var init_stats_utils = __esm({
 });
 
 // src/demo/fixture.ts
-function makeTest(id, title, status, duration, retries = 0) {
+function makeTest(id, title, status, duration, retries = 0, tags = []) {
   return {
     id,
     title,
@@ -103,7 +103,7 @@ function makeTest(id, title, status, duration, retries = 0) {
     status,
     duration,
     retryCount: retries,
-    tags: [],
+    tags,
     annotations: []
   };
 }
@@ -381,20 +381,20 @@ var init_fixture = __esm({
       machineLimit: 25
     };
     DEMO_AUTH_TESTS = [
-      makeTest("auth-1", "should login with valid credentials", "passed", 1240),
-      makeTest("auth-2", "should show error for wrong password", "passed", 890),
-      makeTest("auth-3", "should require email confirmation", "passed", 1100),
-      makeTest("auth-4", "should handle session timeout gracefully", "flaky", 3200, 1),
-      makeTest("auth-5", "should block brute-force attempts after 5 tries", "failed", 15e3, 2),
-      makeTest("auth-6", "should logout and clear session cookies", "passed", 780)
+      makeTest("auth-1", "should login with valid credentials", "passed", 1240, 0, ["@auth", "@smoke", "@SHOP-1201"]),
+      makeTest("auth-2", "should show error for wrong password", "passed", 890, 0, ["@auth", "@smoke", "@SHOP-1201"]),
+      makeTest("auth-3", "should require email confirmation", "passed", 1100, 0, ["@auth", "@regression", "@SHOP-1188"]),
+      makeTest("auth-4", "should handle session timeout gracefully", "flaky", 3200, 1, ["@auth", "@regression"]),
+      makeTest("auth-5", "should block brute-force attempts after 5 tries", "failed", 15e3, 2, ["@auth", "@regression", "@SHOP-1349"]),
+      makeTest("auth-6", "should logout and clear session cookies", "passed", 780, 0, ["@auth", "@smoke"])
     ];
     DEMO_CHECKOUT_TESTS = [
-      makeTest("co-1", "should add product to cart", "passed", 1050),
-      makeTest("co-2", "should apply valid promo code", "passed", 2100),
-      makeTest("co-3", "should reject expired promo code", "failed", 8e3, 2),
-      makeTest("co-4", "should calculate shipping by region", "passed", 1800),
-      makeTest("co-5", "should complete Stripe checkout", "passed", 4200),
-      makeTest("co-6", "should send order confirmation email", "skipped", 0)
+      makeTest("co-1", "should add product to cart", "passed", 1050, 0, ["@checkout", "@smoke", "@SHOP-1042"]),
+      makeTest("co-2", "should apply valid promo code", "passed", 2100, 0, ["@checkout", "@regression", "@SHOP-1277"]),
+      makeTest("co-3", "should reject expired promo code", "failed", 8e3, 2, ["@checkout", "@regression", "@SHOP-1277"]),
+      makeTest("co-4", "should calculate shipping by region", "passed", 1800, 0, ["@checkout", "@regression"]),
+      makeTest("co-5", "should complete Stripe checkout", "passed", 4200, 0, ["@checkout", "@smoke", "@SHOP-1042"]),
+      makeTest("co-6", "should send order confirmation email", "skipped", 0, 0, ["@checkout"])
     ];
     DEMO_CATALOG_TESTS = [
       makeTest("cat-1", "should display product grid with filters", "passed", 980),
@@ -6362,7 +6362,10 @@ var init_defaults = __esm({
       historySize: 10,
       showTrend: true,
       flakinessTopN: 5,
-      slowTestThreshold: 10
+      slowTestThreshold: 10,
+      // Ticket-ID shape: @ODP-5328, REQ-001, JIRA-123. Tags matching this land in
+      // the Requirements Traceability matrix; the rest fall to the tag summary.
+      requirementTagPattern: "^@?[A-Z][A-Z0-9]*-\\d+$"
     };
   }
 });
@@ -6620,7 +6623,7 @@ function deriveOptions(s) {
     showFullFailures: s.fullFailures
   };
 }
-var import_handlebars, import_fs, import_path, A4_HEIGHT_MM, PAGE_MARGIN_Y_MM, PX_PER_MM, SUITE_CHART_SMALL_MAX, SUITE_CHART_ROWS_PER_CANVAS, SUITE_CHART_ROW_PX, SUITE_CHART_PAD_PX, PAGE_CONTENT_HEIGHT_PX, SLOW_MEDIAN_FACTOR, TemplateEngine;
+var import_handlebars, import_fs, import_path, A4_HEIGHT_MM, PAGE_MARGIN_Y_MM, PX_PER_MM, SUITE_CHART_SMALL_MAX, SUITE_CHART_ROWS_PER_CANVAS, SUITE_CHART_ROW_PX, SUITE_CHART_PAD_PX, PAGE_CONTENT_HEIGHT_PX, NUMERIC_COLLATOR, SLOW_MEDIAN_FACTOR, TemplateEngine;
 var init_engine = __esm({
   "src/templates/engine.ts"() {
     "use strict";
@@ -6640,6 +6643,7 @@ var init_engine = __esm({
     SUITE_CHART_ROW_PX = 18;
     SUITE_CHART_PAD_PX = 56;
     PAGE_CONTENT_HEIGHT_PX = (A4_HEIGHT_MM - 2 * PAGE_MARGIN_Y_MM) * PX_PER_MM;
+    NUMERIC_COLLATOR = new Intl.Collator(void 0, { numeric: true });
     SLOW_MEDIAN_FACTOR = 2;
     TemplateEngine = class {
       constructor() {
@@ -6666,17 +6670,22 @@ var init_engine = __esm({
       setChartjsBundle(inline) {
         this.chartjsInline = inline;
       }
-      render(data, template, userSections, slowTestThreshold) {
+      render(data, template, opts = {}) {
         const layoutPath = import_path.default.join(this.templatesDir, "layouts", `${template}.hbs`);
         if (!import_fs.default.existsSync(layoutPath)) {
           throw new Error(`[reportforge] Template layout not found: ${layoutPath}`);
         }
         const layoutSource = import_fs.default.readFileSync(layoutPath, "utf8");
         const compiledLayout = this.handlebars.compile(layoutSource);
-        const ctx = this.buildContext(data, template, userSections, slowTestThreshold);
+        const ctx = this.assembleContext(
+          data,
+          resolveSections(template, opts.sections),
+          this.readStyle(`${template}.css`),
+          opts
+        );
         return compiledLayout(ctx);
       }
-      renderFromPath(data, filePath, slowTestThreshold) {
+      renderFromPath(data, filePath, opts = {}) {
         if (!this.customTemplateCache.has(filePath)) {
           if (!import_fs.default.existsSync(filePath)) {
             throw new Error(`[reportforge] Custom template not found: ${filePath}`);
@@ -6685,46 +6694,27 @@ var init_engine = __esm({
           this.customTemplateCache.set(filePath, this.handlebars.compile(source));
         }
         const compiledFn = this.customTemplateCache.get(filePath);
-        return compiledFn(this.buildCustomContext(data, slowTestThreshold));
+        return compiledFn(this.assembleContext(data, allSectionsOn(), "", opts));
       }
-      buildCustomContext(data, slowTestThreshold) {
-        const sections = allSectionsOn();
-        const slow = this.buildSlowTests(data);
-        return {
-          ...data,
-          projects: this.enrichProjects(data, slow, sections, slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold),
-          options: deriveOptions(sections),
-          sections,
-          tagGroups: this.buildTagGroups(data),
-          slowTests: slow.ranked,
-          baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
-          templateCSS: "",
-          chartjsScript: this.buildChartjsScript(),
-          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
-          releaseGateTally: buildFailureTally(data.analysis),
-          suiteChartLarge: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX,
-          suiteChartChunks: data.charts.suiteResults.length > SUITE_CHART_SMALL_MAX ? buildSuiteChartChunks(data.charts.suiteResults) : []
-        };
-      }
-      buildContext(data, template, userSections, slowTestThreshold) {
-        const baseCSS = this.fontsBundleCss + "\n" + this.readStyle("base.css");
-        const templateCSS = this.readStyle(`${template}.css`);
-        const sections = resolveSections(template, userSections);
+      assembleContext(data, sections, templateCSS, opts) {
         const options = deriveOptions(sections);
         const slow = this.buildSlowTests(data);
+        const tags = this.buildTagGroups(data, opts.requirementTagPattern);
         return {
           ...data,
           projects: this.enrichProjects(
             data,
             slow,
             sections,
-            slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
+            opts.slowTestThreshold ?? DEFAULT_OPTIONS.slowTestThreshold
           ),
           options,
           sections,
-          tagGroups: this.buildTagGroups(data),
+          tagGroups: tags.all,
+          requirementTagGroups: tags.requirements,
+          categoryTagGroups: tags.categories,
           slowTests: slow.ranked,
-          baseCSS,
+          baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
           templateCSS,
           chartjsScript: this.buildChartjsScript(),
           watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
@@ -6736,7 +6726,7 @@ var init_engine = __esm({
       buildChartjsScript() {
         return this.chartjsInline ? `<script>${this.chartjsInline}</script>` : "<!-- Chart.js not bundled; charts disabled --><script>window.__chartsReady=true;</script>";
       }
-      buildTagGroups(data) {
+      buildTagGroups(data, requirementTagPattern) {
         const tagMap = /* @__PURE__ */ new Map();
         for (const project of data.projects) {
           for (const suite of this.flattenSuites(project.suites)) {
@@ -6751,11 +6741,20 @@ var init_engine = __esm({
             }
           }
         }
-        return Array.from(tagMap.entries()).map(([tag, counts]) => ({
-          tag,
-          ...counts,
-          coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
-        }));
+        const regex = new RegExp(requirementTagPattern ?? DEFAULT_OPTIONS.requirementTagPattern);
+        const requirements = [];
+        const categories = [];
+        for (const [tag, counts] of tagMap) {
+          const row = {
+            tag,
+            ...counts,
+            coveragePct: counts.total > 0 ? Math.round(counts.passed / counts.total * 100) : 0
+          };
+          (regex.test(tag) ? requirements : categories).push(row);
+        }
+        requirements.sort((a, b) => NUMERIC_COLLATOR.compare(a.tag, b.tag));
+        categories.sort((a, b) => b.total - a.total || a.tag.localeCompare(b.tag));
+        return { all: [...requirements, ...categories], requirements, categories };
       }
       buildSlowTests(data) {
         const tests = [];
@@ -7858,7 +7857,12 @@ var init_PdfGenerator = __esm({
         }
         const templateLabel = source.kind === "builtin" ? source.id : source.label;
         logger.info(`Rendering template: ${templateLabel}`);
-        const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, options.sections, options.slowTestThreshold) : this.templateEngine.renderFromPath(renderData, source.absolutePath, options.slowTestThreshold);
+        const renderOpts = {
+          sections: options.sections,
+          slowTestThreshold: options.slowTestThreshold,
+          requirementTagPattern: options.requirementTagPattern
+        };
+        const html = source.kind === "builtin" ? this.templateEngine.render(renderData, source.id, renderOpts) : this.templateEngine.renderFromPath(renderData, source.absolutePath, renderOpts);
         const tempHtmlPath = await this.htmlWriter.write(html);
         const fileUrl = this.htmlWriter.toFileUrl(tempHtmlPath);
         try {
@@ -12133,6 +12137,14 @@ var init_schema = __esm({
       remoteHistory: external_exports.boolean().default(false),
       flakinessTopN: external_exports.number().int().min(0, "flakinessTopN must be 0 or greater").optional().default(DEFAULT_OPTIONS.flakinessTopN),
       slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
+      requirementTagPattern: external_exports.string().refine((v) => {
+        try {
+          new RegExp(v);
+          return true;
+        } catch {
+          return false;
+        }
+      }, "requirementTagPattern must be a valid regular expression").optional().default(DEFAULT_OPTIONS.requirementTagPattern),
       failureAnalysis: failureAnalysisConfigSchema,
       capture: captureConfigSchema,
       live: liveConfigSchema,

package/dist/index.d.mts

@@ -202,7 +202,7 @@ interface ReporterOptions {
     };
     /**
      * Offline failure root-cause analysis. Classifies failures into categories
-     * using an embedded Naive Bayes model and renders a clustered breakdown in
+     * using an embedded classifier model and renders a clustered breakdown in
      * the `detailed` PDF (one-liner in `executive`). No network calls at runtime.
      * Optionally personalizes on YOUR machine: label collected failures
      * (`label-feedback`), then `train-model` trains + evaluates a local layer that
@@ -230,9 +230,9 @@ interface ReporterOptions {
          */
         collectScope?: 'blind-spots' | 'all';
         /**
-         * Auto-update the BASE classifier model from the signed license-refresh channel
-         * (offline-tolerant; the bundled model is always the floor; the delivered model
-         * is Ed25519-verified). Set false to pin the bundled model for reproducibility.
+         * Auto-update the BASE classifier model (offline-tolerant; the bundled
+         * model is always the floor; delivered models are signature-verified).
+         * Set false to pin the bundled model for reproducibility.
          * Default: true
          */
         autoUpdateModel?: boolean;
@@ -335,10 +335,10 @@ interface ReporterOptions {
     /**
      * Store the pass-rate trend on the ReportForge server so it survives
      * ephemeral CI runners (where the local history file is wiped every run).
-     * One request per run over the existing license connection, carrying
-     * AGGREGATE NUMBERS ONLY — pass rate, counts, duration, verdict. No test
-     * titles, no error text; even the branch name is sent as a hash. Falls back
-     * to the local history file on any failure.
+     * One small authenticated request per run, carrying AGGREGATE NUMBERS ONLY —
+     * pass rate, counts, duration, verdict. No test titles, no error text; even
+     * the branch name never travels in plaintext. Falls back to the local
+     * history file on any failure.
      * @default false
      */
     remoteHistory?: boolean;
@@ -357,6 +357,17 @@ interface ReporterOptions {
      * @default 10
      */
     slowTestThreshold?: number;
+    /**
+     * Regex (string) deciding which tags count as requirement IDs in the
+     * Requirements Traceability section. Matching tags get the traceability
+     * matrix; the rest collapse into a compact tag summary, so suite-level
+     * category tags (`@regression`, `@sanity`) no longer repeat identical
+     * rows. The default matches ticket-ID shapes such as `@ODP-5328`,
+     * `REQ-001`, or `JIRA-123` (uppercase key, dash, digits). Set to `''` to
+     * disable the split and list every tag in the matrix (legacy behavior).
+     * @default '^@?[A-Z][A-Z0-9]*-\\d+$'
+     */
+    requirementTagPattern?: string;
     /**
      * Path to a custom Handlebars (.hbs) template file. When set, takes
      * precedence over `template`. Relative paths resolve from `process.cwd()`.

package/dist/index.d.ts

@@ -202,7 +202,7 @@ interface ReporterOptions {
     };
     /**
      * Offline failure root-cause analysis. Classifies failures into categories
-     * using an embedded Naive Bayes model and renders a clustered breakdown in
+     * using an embedded classifier model and renders a clustered breakdown in
      * the `detailed` PDF (one-liner in `executive`). No network calls at runtime.
      * Optionally personalizes on YOUR machine: label collected failures
      * (`label-feedback`), then `train-model` trains + evaluates a local layer that
@@ -230,9 +230,9 @@ interface ReporterOptions {
          */
         collectScope?: 'blind-spots' | 'all';
         /**
-         * Auto-update the BASE classifier model from the signed license-refresh channel
-         * (offline-tolerant; the bundled model is always the floor; the delivered model
-         * is Ed25519-verified). Set false to pin the bundled model for reproducibility.
+         * Auto-update the BASE classifier model (offline-tolerant; the bundled
+         * model is always the floor; delivered models are signature-verified).
+         * Set false to pin the bundled model for reproducibility.
          * Default: true
          */
         autoUpdateModel?: boolean;
@@ -335,10 +335,10 @@ interface ReporterOptions {
     /**
      * Store the pass-rate trend on the ReportForge server so it survives
      * ephemeral CI runners (where the local history file is wiped every run).
-     * One request per run over the existing license connection, carrying
-     * AGGREGATE NUMBERS ONLY — pass rate, counts, duration, verdict. No test
-     * titles, no error text; even the branch name is sent as a hash. Falls back
-     * to the local history file on any failure.
+     * One small authenticated request per run, carrying AGGREGATE NUMBERS ONLY —
+     * pass rate, counts, duration, verdict. No test titles, no error text; even
+     * the branch name never travels in plaintext. Falls back to the local
+     * history file on any failure.
      * @default false
      */
     remoteHistory?: boolean;
@@ -357,6 +357,17 @@ interface ReporterOptions {
      * @default 10
      */
     slowTestThreshold?: number;
+    /**
+     * Regex (string) deciding which tags count as requirement IDs in the
+     * Requirements Traceability section. Matching tags get the traceability
+     * matrix; the rest collapse into a compact tag summary, so suite-level
+     * category tags (`@regression`, `@sanity`) no longer repeat identical
+     * rows. The default matches ticket-ID shapes such as `@ODP-5328`,
+     * `REQ-001`, or `JIRA-123` (uppercase key, dash, digits). Set to `''` to
+     * disable the split and list every tag in the matrix (legacy behavior).
+     * @default '^@?[A-Z][A-Z0-9]*-\\d+$'
+     */
+    requirementTagPattern?: string;
     /**
      * Path to a custom Handlebars (.hbs) template file. When set, takes
      * precedence over `template`. Relative paths resolve from `process.cwd()`.