[codex] Document coverage-backed validation gate

.github/pull_request_template.md

@@ -8,11 +8,8 @@ required local checks, and when docs or changelog updates are expected.
 
 ## Verification
 
-- [ ] `npm run lint`
-- [ ] `npm run format:check`
-- [ ] `npm run build`
-- [ ] `npm test`
-- [ ] `npm run pack:check`
+- [ ] `npm run validate`
+- [ ] manual verification noted below if applicable
 
 ## Notes
 

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ permissions:
 
 jobs:
   test:
-    name: Build and test
+    name: Validation gate
     runs-on: ubuntu-latest
 
     steps:
@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Validate release gates
+      - name: Run full validation gate
         run: npm run validate
 
   dependency-vulnerabilities:
@@ -55,7 +55,7 @@ jobs:
         run: npm audit --audit-level=high
 
   trivy:
-    name: Trivy scan
+    name: Trivy scan (informational)
     runs-on: ubuntu-latest
 
     steps:

CONTRIBUTING.md

@@ -38,17 +38,21 @@ Install dependencies before running checks:
 npm install
 ```
 
-Run this full verification set before opening or updating a pull request unless
-you explain why a specific check was skipped:
+Run the canonical verification command before opening or updating a pull request
+unless you explain why it was skipped:
 
 ```bash
-npm run lint
-npm run format:check
-npm run build
-npm test
-npm run pack:check
+npm run validate
 ```
 
+`npm run validate` runs:
+
+- `npm run lint`
+- `npm run format:check`
+- `npm run build`
+- `npm run test:coverage`
+- `npm run pack:check`
+
 You can run the CLI locally with:
 
 ```bash
@@ -58,6 +62,8 @@ npm run cli -- <command>
 ## Tests, Docs, And Changelog Expectations
 
 - Behavior changes should include focused Vitest coverage near the closest existing suite in `test/`.
+- `npm test` remains available as the quick unit-test path, but `npm run validate` is the required merge gate.
+- Live integration tests are manual-only, require local credentials, and stay outside `npm run validate`, CI, and release automation unless a task explicitly calls for that verification.
 - Avoid tests that require live credentials or network access unless the change explicitly calls for manual verification.
 - User-facing SDK or CLI changes should update [`README.md`](./README.md).
 - User-facing SDK or CLI changes should also update [`CHANGELOG.md`](./CHANGELOG.md).

README.md

@@ -335,11 +335,8 @@ notes, and badge-homepage guidance are documented in
 
 ```bash
 npm install
-npm run lint
-npm run format:check
-npm run build
+npm run validate
 npm run openapi:generate
-npm run pack:check
 npm run cli -- children list
 npm run cli -- grades list --child <id-or-login>
 ```
@@ -360,6 +357,41 @@ npm run cli -- justifications conferences --child <id-or-login>
 npm run cli -- auth photo --child <id-or-login> --id <photo-id> --output ./photo.jpg
 ```
 
+### Testing And Dynamic Analysis
+
+The required pre-merge verification command for this repository is:
+
+```bash
+npm run validate
+```
+
+`npm run validate` runs the same canonical checks used by the CI validation
+gate:
+
+- `npm run lint`
+- `npm run format:check`
+- `npm run build`
+- `npm run test:coverage`
+- `npm run pack:check`
+
+Behavior changes should add or update focused Vitest coverage in the closest
+relevant suite under `test/`.
+
+This repository's dynamic-analysis evidence is the automated Vitest test suite
+plus coverage checks. That evidence comes from `npm run test:coverage` locally
+and the `Validation gate` CI job in
+[`./.github/workflows/ci.yml`](./.github/workflows/ci.yml).
+
+For Best Practices and repository-policy purposes, this project does not rely on
+fuzzing or browser scanning as its dynamic-analysis evidence.
+
+Current CI jobs:
+
+- `Validation gate`: runs the required `npm run validate` path before merge.
+- `Dependency vulnerability gate`: fails on high or critical npm advisories.
+- `Trivy scan (informational)`: publishes vulnerability and secret-scan results
+  for review.
+
 ## Live Integration Tests
 
 This repo also includes optional live integration tests for the built SDK and
@@ -368,6 +400,7 @@ CLI artifacts in `dist`.
 They are intended for local manual verification only:
 
 - they require real Librus credentials
+- they are manual-only and not required for ordinary merges
 - they are not part of `npm test`
 - they are not part of `npm run validate`
 - they are not run in CI or release automation

package.json

@@ -40,7 +40,7 @@
     "report:integration": "npm run build && node --env-file=.env.integration.local test/integration/report-all.mjs",
     "report:integration:cli": "npm run build && node --env-file=.env.integration.local test/integration/report-cli.mjs",
     "report:integration:sdk": "npm run build && node --env-file=.env.integration.local test/integration/report-sdk.mjs",
-    "validate": "npm run lint && npm run format:check && npm run build && npm test && npm run pack:check",
+    "validate": "npm run lint && npm run format:check && npm run build && npm run test:coverage && npm run pack:check",
     "prepublishOnly": "npm run validate",
     "prepare": "husky",
     "test": "vitest run",