@carecard/auth-util 3.12.0 → 3.14.0

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

@@ -7,6 +7,14 @@ Non-negotiable root-cause solution rule: Always identify and solve the verified
 
 # CareCard Workspace Standards
 
+Mandatory companion: load
+`$pkg-auth-util-coding-standards-and-best-practices` before this skill for every
+task in this repository.
+
+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
@@ -26,6 +34,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
@@ -400,7 +410,7 @@ the authenticated dashboard.
 - `ms-auth` follows the shared PostgreSQL/RLS pattern: auth tables live in the `carecard` schema, RLS is enabled and forced on every auth table, and application runtime queries use the unprivileged database role.
 - Auth table policies allow normal JWT users to access only self-owned rows. Do not add redundant `user_id = <jwt sub>` SQL predicates to duplicate self-row checks when RLS owns the authorization decision.
 - A JWT payload containing `roles: ["ad"]` is the auth-service super-admin signal and can perform any action on auth tables. Dashboard code may map that role to `super_admin`, but backend auth RLS must not require a separate database role row for that bypass.
-- Public auth flows such as registration, login, confirmation, recovery, visitor creation, and service user lookup must use narrow system contexts (`system_create`, `system_login`, `system_confirm`, `system_recovery`, `system_visitor`, `system_service`) instead of privileged runtime queries.
+- Public auth flows such as registration, login, recovery, visitor creation, and service user lookup must use narrow system contexts (`system_create`, `system_login`, `system_recovery`, `system_visitor`, `system_service`) instead of privileged runtime queries.
 
 - `ms-auth` controller exports use concise action names such as `loginUser`,
   `registerUser`, `getUserDetail`, and `renewJwt`; route middleware and router
@@ -410,7 +420,7 @@ the authenticated dashboard.
 
 ## Security Requirements
 
-- Treat authentication, authorization, JWT, password, email confirmation,
+- Treat authentication, authorization, JWT, password, email verification,
   recovery, file upload, CORS, rate limits, and error response behavior as
   security-sensitive.
 - Never log or return secrets, tokens, passwords, credentials, private keys,

package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md

@@ -13,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
@@ -247,3 +249,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-auth-util-coding-standards-and-best-practices/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: pkg-auth-util-coding-standards-and-best-practices
+description: 'Mandatory for every pkg-auth-util task, including analysis, clarification, planning, implementation, review, debugging, documentation, public API work, skill maintenance, and validation. Use before every narrower skill.'
+---
+
+# Pkg Auth Util Coding Standards And Best Practices
+
+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.
+
+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 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.
+
+## Mandatory Use And Authorities
+
+Load this skill before doing any work in `pkg-auth-util`, including read-only
+and documentation-only work. Then load every narrower skill that owns the
+affected package contract.
+
+Use these existing authorities instead of duplicating them:
+
+- `$carecard-workspace-standards` for TDD, root-cause solutions, dependencies,
+  errors, isolation, and repository workflow;
+- `$software-design-patterns-and-clean-code` for design, DRY, KISS,
+  testability, and clean-code details;
+- `$pkg-auth-util-auth-crypto-library` for cryptography, package architecture,
+  exports, types, security, and validation; and
+- `$pkg-publish` only when runtime package artifacts or consumer versions must
+  be published and propagated.
+
+This skill adds the function-evolution, direct-contract, composition, and
+completion rules below without weakening those companion skills.
+
+## Requirement Judgment
+
+1. Read the complete request and inspect implementation, public exports,
+   declarations, tests, documentation, and consumers before deciding how to
+   change the package.
+2. Translate the request into a coherent technical contract. Do not apply
+   wording mechanically when it is contradictory, unsafe, impossible, or
+   incompatible with cryptographic or package architecture.
+3. Make low-risk, reversible assumptions only when they preserve requested
+   behavior and scope.
+4. Ask for clarification when an unresolved choice would materially change a
+   public API, cryptographic behavior, security, consumer behavior, destructive
+   scope, or the repositories that must change.
+5. Explain architectural tradeoffs before a major API, type, crypto, module,
+   package, or dependency change.
+
+## Scope And Quality
+
+- Treat every workspace repository as independent and validate it from its own
+  root.
+- Update every skill, document, source, runtime test, type test, export,
+  declaration, consumer, and package version genuinely required for a coherent
+  task.
+- Do not broaden the task into unrelated cleanup.
+- Preserve CommonJS structure, established public surfaces, naming, and test
+  conventions unless the task explicitly replaces them.
+- Prefer Node core and existing helpers over new dependencies.
+- Prefer readable direct implementation over clever compression or a temporary
+  workaround.
+- Use meaningful names that describe authentication and cryptographic intent.
+
+## Function Evolution
+
+Before changing a function's behavior or signature, inventory every direct,
+indirect, test, exported, callback, configuration-driven, and dynamic consumer.
+
+- If exactly one consumer is proven, change the function only when required.
+- If two or more consumers exist, do not change the shared function's behavior.
+  Create a new purpose-named function and migrate only intended consumers.
+- If every consumer needs the new contract, migrate all consumers and delete
+  the old function after proving it unused.
+- Treat every exported, declared, public, callback, or dynamically discovered
+  function as shared unless single use is conclusively proven.
+- Do not add caller branches, mode flags, or optional parameters merely to
+  make one shared function serve incompatible contracts.
+- Cover the new function, public surface, types, and every migrated consumer
+  through TDD.
+
+## Direct Contract Without Backward Compatibility
+
+When the active task replaces a contract, implement the requested end state
+directly. Do not add legacy aliases, deprecated wrappers, compatibility
+overloads, duplicate exports, dual paths, transitional names, or fallback
+behavior solely to preserve the superseded contract.
+
+Delete obsolete functions and exports after all intended consumers have
+migrated and repository-native search, runtime tests, and type tests prove them
+unused. This does not authorize unrelated API removal. If an existing
+published or security contract requires compatibility and the request does not
+clearly supersede it, explain the conflict and ask before changing it.
+
+## TDD And Root-Cause Gate
+
+Follow `$carecard-workspace-standards` and
+`$pkg-auth-util-auth-crypto-library` for the complete failing-test-first and
+root-cause workflow. Documentation and skill changes require a focused
+structural validation before prose changes. Do not accept retries, suppressed
+diagnostics, weakened types, disabled tests, forced success, compatibility
+patches, or symptom-only workarounds as completion.
+
+## Function Size
+
+Every new or materially changed function must contain at most 25 logical code
+lines.
+
+- Count executable statements, branches, loop headers, side-effecting calls,
+  returns, and throws.
+- Exclude signatures, type-only declarations, blank lines, comments, and
+  isolated braces.
+- Extract cohesive purpose-named helpers and compose them when needed.
+- Keep crypto parsing, validation, transformation, signing, and error
+  responsibilities explicit rather than hiding them in one long function.
+- Avoid meaningless forwarding wrappers and do not refactor untouched
+  functions solely to satisfy this limit.
+
+## UI Composition
+
+This package does not own UI. If a package contract requires UI changes, make
+them in the owning app repository. There, create focused components, compose
+existing and new components, and delete obsolete components only after proving
+them unused and replaced.
+
+## Skills, Documentation, And Database Boundaries
+
+- Update affected skills, README guidance, examples, exports, and declarations
+  with behavior or validation changes.
+- Reference existing authoritative skills instead of copying their details.
+- If work reaches an `ms-*` database, change SQL only in the owning repository
+  using its database-migration-ownership skill. For first-create work, edit the
+  existing migration and matching rollback directly rather than adding a
+  compatibility migration.
+- Keep persistence and service behavior in their owning repositories.
+
+## Completion
+
+1. Review each changed repository's diff and status independently.
+2. Run focused runtime and type tests, then all broader checks required by
+   local skills.
+3. If every changed file in a repository is Markdown (`*.md`), skip Husky and
+   run only focused Markdown validation.
+4. If any changed file is not Markdown, run every direct `.husky` script. If
+   none exists, run the strongest repository-native focused validation.
+5. Fix every in-scope failure at its root cause and rerun the exact command.
+6. Report exact commands, results, limitations, and remaining risk.
+7. Do not perform remote Git or GitHub operations unless explicitly requested.

package/.agents/skills/pkg-auth-util-coding-standards-and-best-practices/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Pkg Auth Util Coding Standards'
+  short_description: 'Apply mandatory auth package standards'
+  default_prompt: 'Use $pkg-auth-util-coding-standards-and-best-practices before every pkg-auth-util task and apply all narrower skills that the task requires.'

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

@@ -13,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/AGENTS.md

@@ -0,0 +1,15 @@
+# Codex Instructions
+
+## Non-negotiable Codex banked-reset requirement
+
+- Never use or consume a banked Codex rate-limit reset automatically.
+- Before using any banked Codex rate-limit reset, stop, ask the user for explicit, direct approval for that specific reset, and wait for their reply.
+- Never treat earlier approval, a standing instruction, silence, urgency, an unfinished task, or a request to continue as approval for a future reset.
+- Do not invoke `/usage` redemption, a reset-consumption action, a reset API or tool, or any equivalent mechanism unless the user explicitly approved that specific reset.
+- If a Codex limit is reached without that approval, pause and let the user reset it manually. Never consume a banked reset to keep working.
+
+## Repository validation contracts
+
+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 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.

package/index.d.ts

@@ -2,7 +2,7 @@
  * Utility functions for authentication and authorization in the CareCard ecosystem.
  */
 
-import { Request } from 'express';
+import type { Request } from 'express';
 
 /**
  * Represents the standard JWT header structure.
@@ -14,7 +14,7 @@ export interface JwtHeader {
   typ?: string;
 
   /** Any other custom header fields. */
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -35,7 +35,7 @@ export interface JwtPayload {
   roles?: string[];
 
   /** Any other custom payload fields. */
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -89,10 +89,10 @@ export interface JwtRequestObject {
   header: JwtHeader;
   payload: JwtPayload;
   age?: number;
-  jwtClientId: (req?: any) => string | undefined;
+  jwtClientId: (req?: AuthenticatedRequest) => string | undefined;
   doesJwtUserHasRole: (role: string) => boolean;
   isJwtExpired: (jwtValiditySeconds?: number) => boolean;
-  jwtAgeInSeconds: (req?: any) => number;
+  jwtAgeInSeconds: (req?: AuthenticatedRequest) => number;
 }
 
 /**
@@ -101,7 +101,7 @@ export interface JwtRequestObject {
 export interface VisitorRequestObject {
   header: JwtHeader;
   payload: JwtPayload;
-  visitorClientId: (req?: any) => string | undefined;
+  visitorClientId: (req?: AuthenticatedRequest) => string | undefined;
 }
 
 /**
@@ -248,14 +248,14 @@ export const stringUtilAuth: {
    * @param object - The object to serialize.
    * @returns URL-safe base64 string.
    */
-  objectToBase64UrlSafeString: (object: any) => string;
+  objectToBase64UrlSafeString: (object: unknown) => string;
   /**
    * Parses a URL-safe base64 string into an object.
    * @deprecated Use native Buffer methods or other modern alternatives.
    * @param urlSafeBase64String - URL-safe base64 string.
    * @returns The parsed object.
    */
-  urlSafeBase64ToObject: (urlSafeBase64String: string) => any;
+  urlSafeBase64ToObject: (urlSafeBase64String: string) => unknown;
 };
 
 /**

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "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,14 +42,15 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.12.0",
-    "@carecard/validate": "3.12.0",
+    "@carecard/common-util": "3.14.0",
+    "@carecard/validate": "3.14.0",
     "@types/express": "5.0.6"
   },
   "overrides": {
     "diff": "8.0.4",
     "glob": "13.0.6",
+    "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,7 @@
 # @carecard/auth-util
 
+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-auth-util/actions/workflows/ci.yml/badge.svg)
@@ -15,6 +17,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
@@ -150,3 +154,21 @@ The package is organized into several modules:
 - `stringUtilAuth`: String manipulation and format conversions.
 
 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/);
+});