@carecard/jwt-read 3.11.0 → 3.13.0

package/.agents/skills/carecard-workspace-standards/SKILL.md

@@ -3,14 +3,35 @@ name: carecard-workspace-standards
 description: 'Follow the shared SO_CareCardCa/CareCard workspace coding, testing, repository, dependency, shared package, frontend, database, API response, and security standards. Use before modifying, testing, reviewing, or debugging any ms-*, pkg-*, app-*, website, dashboard, or other CareCard repository in this workspace, especially when choosing validation commands, package boundaries, TypeScript types, dependencies, API contracts, database logic, service patterns, or frontend architecture.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # CareCard Workspace Standards
 
+Non-negotiable test order invariance rule: Every test must pass independently of which tests run before or after it, and the suite must pass in every execution order. Each test must establish the state it needs, isolate mutable state, and clean up state it owns; it must never rely on another test's setup, mutations, or cleanup. Default test, CI, and Husky commands must use the test framework's ordinary ordering and must not force randomized ordering. Random-order execution is an explicit diagnostic only, and every failure it exposes must be fixed at the root cause.
+
+Non-negotiable parallel test execution rule: Run independent test files in parallel with repository-native worker support wherever resource isolation makes parallel execution safe. Tests that share a mutable database, application server, browser state, filesystem fixture, port, or cluster resource must remain in an explicitly isolated serial group until every worker owns a separate resource. Parallel execution must preserve ordinary test selection and must never use randomized ordering, retries, locks, or error suppression to conceal coupling.
+
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+This requirement is non-negotiable and may be overridden only with the user's
+explicit, direct approval.
+
+A pre-existing test—defined as any test present before work on the current task
+begins—must not be deleted, disabled, skipped, weakened, excluded from execution,
+or otherwise removed. A pre-existing test must not be modified without the
+user's explicit approval for the exact proposed change. If changing a
+pre-existing test is believed necessary, stop before making the change and
+request approval. The request must identify every affected test, describe the
+precise proposed modification, provide detailed technical justification, and
+explain all known or reasonably foreseeable regression risks. Until approval is
+granted, leave every pre-existing test unchanged.
+
 Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
 
 Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
 
+Non-negotiable TypeScript type rule: Never use the TypeScript type `any`; always use specific domain types, generics, existing project types, or `unknown` with explicit narrowing in all TypeScript-family files (`.ts`, `.tsx`, `.mts`, `.cts`, and `.d.ts`).
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose

package/.agents/skills/github-pr-create-update/SKILL.md

@@ -3,6 +3,8 @@ name: github-pr-create-update
 description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating or updating a PR, or marking a PR ready from the current repository branch into development or main.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Pull Request Create
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -3,6 +3,8 @@ name: github-pr-merge-cleanup
 description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating a missing PR, reviewing mergeability, validating, merging, deleting, or cleaning up a pull request branch.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Pull Request Merge Close
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.

package/.agents/skills/pkg-jwt-read-jwt-middleware-library/SKILL.md

@@ -3,6 +3,8 @@ name: pkg-jwt-read-jwt-middleware-library
 description: 'Use when changing pkg-jwt-read JWT parsing, middleware, visitor tokens, role checks, auth context, package exports, or tests.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Package JWT Read
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
@@ -11,6 +13,8 @@ Non-negotiable repository isolation rule: Every repository must run its Husky ho
 
 Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
 
+Non-negotiable TypeScript type rule: Never use the TypeScript type `any`; always use specific domain types, generics, existing project types, or `unknown` with explicit narrowing in all TypeScript-family files (`.ts`, `.tsx`, `.mts`, `.cts`, and `.d.ts`).
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose
@@ -285,3 +289,21 @@ repository's agents-only Git workflow:
 Do not commit or push `.agents` guidance changes directly from `development`
 or `main`. Do not stage unrelated files, generated output, dependency folders,
 build artifacts, logs, or `.DS_Store`.
+
+## Fail-Closed Test Lifecycle Audit
+
+The current package tests own no HTTP listener, database pool, Kafka client,
+background timer, or child process after completion. Mocha's test timeout fails
+a stalled async test, the suites run without bail or forced exit, and npm
+preserves each command's nonzero status. Keep natural process exit as the open
+handle regression check; validation must not hide failures with retries, forced
+success, skipped tests, or output suppression.
+
+Do not add unpublished executable validation code to a `pkg-*` repository. If a
+future test owns a long-lived resource or demonstrates a post-suite hang, add a
+contract-tested process watchdog through the coordinated package version,
+publish, and consumer propagation workflow. That watchdog must return
+immediately when no helper remains, allow only a bounded 250 ms settlement
+window for already-stopping helpers, fail persistent descendants, preserve
+failures and output, use exit code `124` only for a real outer deadline, and
+remain a final guard rather than a substitute for explicit cleanup.

package/.agents/skills/pkg-publish/SKILL.md

@@ -3,6 +3,8 @@ name: pkg-publish
 description: 'Use when any pkg-* repository has non-Markdown package changes, including source code, public types, tests, scripts, package metadata, lockfiles, dependency behavior, or validation config, and the CareCard packages must be versioned, published in order with just-in-time package pushes, and propagated to pkg-*, ms-*, and app-dashboard consumers. Do not use for Markdown-only changes.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # pkg Publish
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.

package/.agents/skills/software-design-patterns-and-clean-code/SKILL.md

@@ -3,6 +3,8 @@ name: software-design-patterns-and-clean-code
 description: 'Use every time before coding, refactoring, debugging, or reviewing in this repository, alongside all other applicable skills, to apply pragmatic software design patterns, SOLID, Clean Code, and testable architecture.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Software Design Patterns And Clean Code
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
@@ -11,6 +13,8 @@ Non-negotiable repository isolation rule: Every repository must run its Husky ho
 
 Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
 
+Non-negotiable TypeScript type rule: Never use the TypeScript type `any`; always use specific domain types, generics, existing project types, or `unknown` with explicit narrowing in all TypeScript-family files (`.ts`, `.tsx`, `.mts`, `.cts`, and `.d.ts`).
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose

package/index.d.ts

@@ -2,7 +2,7 @@
  * Utility functions for authentication and authorization in the CareCard ecosystem.
  */
 
-import { NextFunction, Request, Response } from 'express';
+import type { NextFunction, Request, Response } from 'express';
 
 export const DEFAULT_USER_AUTHORIZATION_HEADER_NAME: 'X-Authorization-Context';
 export const DEFAULT_USER_AUTHORIZATION_MAX_TOKEN_LENGTH: 2048;
@@ -16,7 +16,7 @@ export interface JwtHeader {
   /** The media type of the JWT. Defaults to 'JWT'. */
   typ?: string;
   /** Any other custom header fields. */
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -40,7 +40,7 @@ export interface JwtPayload {
   /** Server-auth session identifier when an opaque server-auth token was used. */
   sessionId?: string;
   /** Any other custom payload fields. */
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -76,10 +76,10 @@ export interface JwtRequestObject {
   header: JwtHeader;
   payload: JwtPayload;
   age?: number;
-  jwtClientId: (req?: any) => string | undefined;
+  jwtClientId: (req?: JwtRequestContext) => string | undefined;
   doesJwtUserHasRole: (role: string) => boolean;
   isJwtExpired: (jwtValiditySeconds?: number) => boolean;
-  jwtAgeInSeconds: (req?: any) => number;
+  jwtAgeInSeconds: (req?: JwtRequestContext) => number;
 }
 
 /**
@@ -88,7 +88,7 @@ export interface JwtRequestObject {
 export interface VisitorRequestObject {
   header: JwtHeader;
   payload: JwtPayload;
-  visitorClientId: (req?: any) => string | undefined;
+  visitorClientId: (req?: JwtRequestContext) => string | undefined;
 }
 
 /**
@@ -99,6 +99,24 @@ export interface UserAuthorizationRequestObject {
   payload: UserAuthorizationPayload;
 }
 
+export interface JwtRequestContext {
+  jwt?: {
+    header?: JwtHeader;
+    payload: JwtPayload;
+    age?: number;
+    jwtClientId?: JwtRequestObject['jwtClientId'];
+    doesJwtUserHasRole?: JwtRequestObject['doesJwtUserHasRole'];
+    isJwtExpired?: JwtRequestObject['isJwtExpired'];
+    jwtAgeInSeconds?: JwtRequestObject['jwtAgeInSeconds'];
+  } | null;
+  visitor?: {
+    header?: JwtHeader;
+    payload: JwtPayload;
+    visitorClientId?: VisitorRequestObject['visitorClientId'];
+  } | null;
+  userAuthorization?: UserAuthorizationRequestObject | null;
+}
+
 export interface UserAuthorizationTokenOptions {
   publicKey?: string;
   headerName?: string;
@@ -115,7 +133,7 @@ export interface UserAuthorizationReadOptions {
 /**
  * Extended Express Request to include jwt, visitor, and userAuthorization objects.
  */
-export interface AuthenticatedRequest extends Request {
+export interface AuthenticatedRequest extends Request, JwtRequestContext {
   jwt?: JwtRequestObject | null;
   visitor?: VisitorRequestObject | null;
   userAuthorization?: UserAuthorizationRequestObject | null;
@@ -137,7 +155,7 @@ export interface ServerAuthIntrospectionClaims {
   exp?: number | string;
   expiresAt?: string;
   expires_at?: string;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 export type ServerAuthIntrospector = (
@@ -214,24 +232,24 @@ export function jwtVerifyVisitorNoThrow(
 /**
  * Returns the sub from the extracted JWT in req.jwt.
  */
-export function jwtGetClientId(req?: any): string | undefined;
+export function jwtGetClientId(req?: JwtRequestContext): string | undefined;
 
 /**
  * Returns the sub from the extracted visitor token in req.visitor.
  */
-export function jwtGetVisitorClientId(req?: any): string | undefined;
+export function jwtGetVisitorClientId(req?: JwtRequestContext): string | undefined;
 
 /**
  * Checks if the extracted JWT in req.jwt has expired.
  */
-export function jwtIsExpired(req: any, jwtValiditySeconds?: number): boolean;
+export function jwtIsExpired(req: JwtRequestContext, jwtValiditySeconds?: number): boolean;
 export function jwtIsExpired(jwtValiditySeconds: number): boolean;
 export function jwtIsExpired(): boolean;
 
 /**
  * Returns the age of the extracted JWT in seconds.
  */
-export function jwtGetAgeInSeconds(req?: any): number;
+export function jwtGetAgeInSeconds(req?: JwtRequestContext): number;
 
 /**
  * Returns a middleware that verifies the JWT and checks if the user has the required role.
@@ -295,7 +313,7 @@ export interface JwtContext {
  * Always returns user_id. If the roles array contains 'ad', also returns role: 'super_admin'.
  * If req.userAuthorization is present, also returns authorizationContext and userAuthorization.
  */
-export function jwtGetContext(req: any): JwtContext;
+export function jwtGetContext(req: JwtRequestContext): JwtContext;
 
 /**
  * Validates the JWT from the Authorization header and extracts it into req.jwt.
@@ -454,19 +472,19 @@ export function verifyVisitorNoThrow(
  * Returns the sub from the extracted JWT in req.jwt.
  * @deprecated use jwtGetClientId
  */
-export function jwtClientId(req?: any): string | undefined;
+export function jwtClientId(req?: JwtRequestContext): string | undefined;
 
 /**
  * Returns the sub from the extracted visitor token in req.visitor.
  * @deprecated use jwtGetVisitorClientId
  */
-export function visitorClientId(req?: any): string | undefined;
+export function visitorClientId(req?: JwtRequestContext): string | undefined;
 
 /**
  * Checks if the extracted JWT in req.jwt has expired.
  * @deprecated use jwtIsExpired
  */
-export function isJwtExpired(req: any, jwtValiditySeconds?: number): boolean;
+export function isJwtExpired(req: JwtRequestContext, jwtValiditySeconds?: number): boolean;
 /** @deprecated use jwtIsExpired */
 export function isJwtExpired(jwtValiditySeconds: number): boolean;
 /** @deprecated use jwtIsExpired */
@@ -476,7 +494,7 @@ export function isJwtExpired(): boolean;
  * Returns the age of the extracted JWT in seconds.
  * @deprecated use jwtGetAgeInSeconds
  */
-export function jwtAgeInSeconds(req?: any): number;
+export function jwtAgeInSeconds(req?: JwtRequestContext): number;
 
 /**
  * Returns a middleware that verifies the JWT and checks if the user has the required role.
@@ -499,7 +517,7 @@ export function throwUsedTokenError(): never;
  * Checks if the user in the extracted JWT has the specified role.
  * @deprecated use jwtDoesJwtUserHasRole
  */
-export function doesJwtUserHasRole(req: any, userRole: string): boolean;
+export function doesJwtUserHasRole(req: JwtRequestContext, userRole: string): boolean;
 /** @deprecated use jwtDoesJwtUserHasRole */
 export function doesJwtUserHasRole(userRole: string): boolean;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"
@@ -9,9 +9,10 @@
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
-    "test": "mocha --recursive",
-    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts",
-    "test:coverage": "tsc --noEmit && nyc mocha --recursive -r ts-node/register 'test/**/*.{js,ts}'",
+    "test": "npm run test:order && node test/index.test.js",
+    "test:order": "node --test scripts/testOrder/randomizeTestOrder.test.mjs scripts/testOrder/testOrderPolicy.test.mjs scripts/testParallel/runIndexedMochaTests.test.mjs scripts/testParallel/parallelTestPolicy.test.mjs",
+    "test:types": "npm run test:order && tsc --noEmit && mocha --require ./scripts/testOrder/randomizeTestOrder.cjs -r ts-node/register test/types.test.ts",
+    "test:coverage": "npm run test:order && tsc --noEmit && nyc node test/index.test.js",
     "test:All": "npm run test && npm run test:types",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -41,13 +42,14 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/auth-util": "3.11.0",
-    "@carecard/common-util": "3.11.0",
-    "@carecard/validate": "3.11.0"
+    "@carecard/auth-util": "3.13.0",
+    "@carecard/common-util": "3.13.0",
+    "@carecard/validate": "3.13.0"
   },
   "overrides": {
     "diff": "8.0.4",
+    "minimatch": "10.2.5",
     "serialize-javascript": "7.0.5",
-    "js-yaml": "4.2.0"
+    "js-yaml": "4.3.0"
   }
 }

package/readme.md

@@ -1,5 +1,9 @@
 # @carecard/jwt-read
 
+Non-negotiable test order invariance rule: Every test must pass independently of which tests run before or after it, and the suite must pass in every execution order. Each test must establish the state it needs, isolate mutable state, and clean up state it owns; it must never rely on another test's setup, mutations, or cleanup. Default test, CI, and Husky commands must use the test framework's ordinary ordering and must not force randomized ordering. Random-order execution is an explicit diagnostic only, and every failure it exposes must be fixed at the root cause.
+
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 ![Tests Passing](https://github.com/CareCard-ca/pkg-jwt-read/actions/workflows/ci.yml/badge.svg)
 ![Coverage](https://img.shields.io/badge/Coverage-80%25-orange)
 
@@ -16,6 +20,8 @@ Non-negotiable repository isolation rule: Every repository must run its Husky ho
 
 Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
 
+Non-negotiable TypeScript type rule: Never use the TypeScript type `any`; always use specific domain types, generics, existing project types, or `unknown` with explicit narrowing in all TypeScript-family files (`.ts`, `.tsx`, `.mts`, `.cts`, and `.d.ts`).
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Features
@@ -225,3 +231,21 @@ The package is organized into several modules:
 - `jwtRoles`: Role mapping between internal codes and names.
 
 All modules are exported through the main `index.js`.
+
+## Fail-Closed Test Lifecycle Audit
+
+The current package tests own no HTTP listener, database pool, Kafka client,
+background timer, or child process after completion. Mocha's test timeout fails
+a stalled async test, the suites run without bail or forced exit, and npm
+preserves each command's nonzero status. Keep natural process exit as the open
+handle regression check; validation must not hide failures with retries, forced
+success, skipped tests, or output suppression.
+
+Do not add unpublished executable validation code to a `pkg-*` repository. If a
+future test owns a long-lived resource or demonstrates a post-suite hang, add a
+contract-tested process watchdog through the coordinated package version,
+publish, and consumer propagation workflow. That watchdog must return
+immediately when no helper remains, allow only a bounded 250 ms settlement
+window for already-stopping helpers, fail persistent descendants, preserve
+failures and output, use exit code `124` only for a real outer deadline, and
+remain a final guard rather than a substitute for explicit cleanup.

package/scripts/testOrder/randomizeTestOrder.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+const MAX_TEST_ORDER_SEED = 2_147_483_647;
+
+function resolveTestOrderSeed(configuredSeed) {
+  if (configuredSeed === undefined) return undefined;
+  if (!/^[1-9]\d*$/.test(configuredSeed)) throw new Error('TEST_ORDER_SEED must be a positive 32-bit integer.');
+  const seed = Number(configuredSeed);
+  if (!Number.isSafeInteger(seed) || seed > MAX_TEST_ORDER_SEED) throw new Error('TEST_ORDER_SEED must be a positive 32-bit integer.');
+  return seed;
+}
+function createSeededRandom(seed) {
+  let state = seed;
+  return function nextRandomValue() {
+    state = (state + 0x6d2b79f5) | 0;
+    let value = Math.imul(state ^ (state >>> 15), 1 | state);
+    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
+    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}
+function shuffleValues(values, random) {
+  for (let index = values.length - 1; index > 0; index -= 1) {
+    const replacementIndex = Math.floor(random() * (index + 1));
+    [values[index], values[replacementIndex]] = [values[replacementIndex], values[index]];
+  }
+}
+function shuffleSuiteTree(suite, random) {
+  for (const childSuite of suite.suites) shuffleSuiteTree(childSuite, random);
+  shuffleValues(suite.tests, random);
+  shuffleValues(suite.suites, random);
+}
+const mochaHooks = {
+  beforeAll() {
+    const seed = resolveTestOrderSeed(process.env.TEST_ORDER_SEED);
+    if (seed === undefined) return;
+    console.log(`Test order seed: ${seed} (reproduce with TEST_ORDER_SEED=${seed})`);
+    shuffleSuiteTree(this.test.parent, createSeededRandom(seed));
+  },
+};
+module.exports = { createSeededRandom, mochaHooks, resolveTestOrderSeed, shuffleSuiteTree };

package/scripts/testOrder/randomizeTestOrder.test.mjs

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import testOrderRandomizer from './randomizeTestOrder.cjs';
+
+const { createSeededRandom, resolveTestOrderSeed, shuffleSuiteTree } = testOrderRandomizer;
+
+function createSuiteTree() {
+  return {
+    suites: [
+      { title: 'alpha', suites: [], tests: [{ title: 'one' }, { title: 'two' }] },
+      { title: 'beta', suites: [], tests: [{ title: 'three' }, { title: 'four' }] },
+      { title: 'gamma', suites: [], tests: [{ title: 'five' }, { title: 'six' }] },
+    ],
+    tests: [{ title: 'root one' }, { title: 'root two' }, { title: 'root three' }],
+  };
+}
+
+test('uses ordinary ordering unless TEST_ORDER_SEED is explicitly supplied', () => {
+  assert.strictEqual(resolveTestOrderSeed(undefined), undefined);
+  assert.strictEqual(resolveTestOrderSeed('314159'), 314159);
+  for (const invalidSeed of ['', '0', '-1', '1.5', 'seed', '2147483648']) {
+    assert.throws(() => resolveTestOrderSeed(invalidSeed), /TEST_ORDER_SEED/);
+  }
+});
+
+test('shuffles nested suites and tests reproducibly', () => {
+  const firstTree = createSuiteTree();
+  const secondTree = createSuiteTree();
+
+  shuffleSuiteTree(firstTree, createSeededRandom(314159));
+  shuffleSuiteTree(secondTree, createSeededRandom(314159));
+
+  assert.deepStrictEqual(firstTree, secondTree);
+  assert.notDeepStrictEqual(firstTree, createSuiteTree());
+});

package/scripts/testOrder/testOrderPolicy.test.mjs

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+const TEST_ORDER_INVARIANCE_RULE =
+  "Non-negotiable test order invariance rule: Every test must pass independently of which tests run before or after it, and the suite must pass in every execution order. Each test must establish the state it needs, isolate mutable state, and clean up state it owns; it must never rely on another test's setup, mutations, or cleanup. Default test, CI, and Husky commands must use the test framework's ordinary ordering and must not force randomized ordering. Random-order execution is an explicit diagnostic only, and every failure it exposes must be fixed at the root cause.";
+
+function listRepositoryFiles() {
+  return execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8' })
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+}
+
+function isRequiredTestGuidance(filePath) {
+  return (
+    /^readme\.md$/i.test(filePath) ||
+    filePath === '.codex/AGENTS.md' ||
+    filePath === '.junie/guidelines.md' ||
+    filePath === '.agents/skills/carecard-workspace-standards/SKILL.md' ||
+    /^\.agents\/skills\/[^/]*(?:test|testing)[^/]*\/(?:SKILL\.md|references\/[^/]*(?:test|testing|coding-principles)[^/]*\.md)$/i.test(
+      filePath,
+    )
+  );
+}
+
+test('keeps the non-negotiable test order rule in repository guidance', () => {
+  const guidanceFiles = listRepositoryFiles().filter(isRequiredTestGuidance);
+  assert.ok(guidanceFiles.length > 0, 'No repository test guidance was found.');
+
+  for (const guidanceFile of guidanceFiles) {
+    const normalizedGuidance = readFileSync(guidanceFile, 'utf8').replace(/\s+/g, ' ').trim();
+    assert.ok(
+      normalizedGuidance.includes(TEST_ORDER_INVARIANCE_RULE),
+      `${guidanceFile} must document the non-negotiable test order invariance rule.`,
+    );
+  }
+});
+
+test('keeps default package scripts on the test framework ordinary ordering', () => {
+  const packageJson = JSON.parse(readFileSync('package.json', 'utf8'));
+
+  for (const [scriptName, command] of Object.entries(packageJson.scripts ?? {})) {
+    assert.equal(typeof command, 'string', `${scriptName} must be a string command.`);
+    assert.doesNotMatch(command, /--test-randomize|--test-random-seed/, `${scriptName} must not force randomized test ordering.`);
+  }
+});

package/scripts/testParallel/parallelTestPolicy.test.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative, resolve } from 'node:path';
+import test from 'node:test';
+
+const require = createRequire(import.meta.url);
+const repositoryRoot = resolve(import.meta.dirname, '../..');
+const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const testIndexSource = readFileSync(new URL('../../test/index.test.js', import.meta.url), 'utf8');
+const { parallelTestFiles } = require('../../test/index.test.js');
+
+function listRuntimeTestFiles(directoryPath) {
+  return readdirSync(directoryPath, { withFileTypes: true }).flatMap(entry => {
+    const entryPath = join(directoryPath, entry.name);
+    if (entry.isDirectory()) return listRuntimeTestFiles(entryPath);
+    if (!/\.test\.(?:js|mjs)$/.test(entry.name) || entry.name === 'index.test.js') {
+      return [];
+    }
+    return [relative(repositoryRoot, entryPath)];
+  });
+}
+
+test('keeps runtime test selection in the index and package scripts short', () => {
+  assert.equal(packageJson.scripts.test, 'npm run test:order && node test/index.test.js');
+  assert.match(packageJson.scripts['test:coverage'], /nyc node test\/index\.test\.js$/);
+  assert.match(testIndexSource, /parallelTestFiles/);
+  assert.match(testIndexSource, /runIndexedMochaTests/);
+  assert.match(testIndexSource, /if \(require\.main === module\)/);
+});
+
+test('runs the parallel execution contract in the test-order gate', () => {
+  assert.match(packageJson.scripts['test:order'], /scripts\/testParallel\/parallelTestPolicy\.test\.mjs/);
+  assert.match(packageJson.scripts['test:order'], /scripts\/testParallel\/runIndexedMochaTests\.test\.mjs/);
+});
+
+test('selects every runtime test file exactly once', () => {
+  assert.deepEqual([...parallelTestFiles].sort(), listRuntimeTestFiles(resolve(repositoryRoot, 'test')).sort());
+});

package/scripts/testParallel/runIndexedMochaTests.cjs

@@ -0,0 +1,71 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const { createRequire } = require('node:module');
+const { availableParallelism } = require('node:os');
+const { resolve } = require('node:path');
+
+const DEFAULT_MAX_PARALLEL_JOBS = 4;
+
+// Pattern: Configuration Boundary - bounds workers without accepting invalid input.
+function resolveParallelJobCount(
+  configuredJobCount,
+  testFileCount,
+  defaultMaximum = DEFAULT_MAX_PARALLEL_JOBS,
+  availableJobCount = availableParallelism(),
+) {
+  const requestedJobCount =
+    configuredJobCount === undefined ? Math.min(availableJobCount, defaultMaximum) : Number.parseInt(configuredJobCount, 10);
+
+  if (!Number.isInteger(requestedJobCount) || requestedJobCount < 1) {
+    throw new Error('TEST_PARALLEL_JOBS must be a positive integer.');
+  }
+  return Math.min(requestedJobCount, testFileCount);
+}
+
+// Pattern: Command Builder - keeps Mocha worker details out of package metadata.
+function buildMochaArguments(testFiles, jobCount) {
+  const requireFromRunner = createRequire(__filename);
+  return [
+    requireFromRunner.resolve('mocha/bin/mocha.js'),
+    '--parallel',
+    '--jobs',
+    String(jobCount),
+    '--require',
+    resolve('scripts/testOrder/randomizeTestOrder.cjs'),
+    ...testFiles,
+  ];
+}
+
+// Pattern: Process Adapter - returns the exact test process result to the index.
+function runIndexedMochaTests(testFiles) {
+  if (testFiles.length === 0) {
+    throw new Error('The package test index must select at least one test file.');
+  }
+
+  const jobCount = resolveParallelJobCount(process.env.TEST_PARALLEL_JOBS, testFiles.length);
+  const child = spawn(process.execPath, buildMochaArguments(testFiles, jobCount), {
+    env: {
+      ...process.env,
+      NODE_ENV: 'test',
+    },
+    stdio: 'inherit',
+  });
+
+  return new Promise((resolveExit, rejectExit) => {
+    child.once('error', rejectExit);
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        rejectExit(new Error(`Mocha exited from signal ${signal}.`));
+        return;
+      }
+      resolveExit(code ?? 1);
+    });
+  });
+}
+
+module.exports = {
+  buildMochaArguments,
+  resolveParallelJobCount,
+  runIndexedMochaTests,
+};

package/scripts/testParallel/runIndexedMochaTests.test.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import test from 'node:test';
+
+const require = createRequire(import.meta.url);
+const { buildMochaArguments, resolveParallelJobCount } = require('./runIndexedMochaTests.cjs');
+
+test('uses bounded Mocha file workers without randomized default ordering', () => {
+  assert.equal(resolveParallelJobCount(undefined, 8, 4, 12), 4);
+  assert.equal(resolveParallelJobCount('2', 8, 4, 12), 2);
+
+  const argumentsList = buildMochaArguments(['test/example.test.js'], 2);
+
+  assert.ok(argumentsList.includes('--parallel'));
+  assert.deepEqual(argumentsList.slice(argumentsList.indexOf('--jobs'), argumentsList.indexOf('--jobs') + 2), ['--jobs', '2']);
+  assert.ok(argumentsList.includes('test/example.test.js'));
+});
+
+test('rejects invalid worker configuration instead of changing execution silently', () => {
+  assert.throws(() => resolveParallelJobCount('0', 8, 4, 12), /TEST_PARALLEL_JOBS must be a positive integer/);
+});