| name | verify-post-feature |
| description | Run and unblock npm run verify:post-feature for the ICT Governance Framework — pre-flight checks, API/DB prerequisites, VB-CP rollback expectations, and troubleshooting. Use before commit, after pillar work, when regression fails, or when the user asks to run the post-feature quality gate. |
Post-feature verification gate (verify:post-feature)
Quality gate QG-VB-CP: validates active contract suites + legacy verify scripts, then rolls back synthetic operational data while preserving immutable ingest audit rows.
When to use
- Before commit or PR after governance/pillar changes
- After implementing a feature listed in
tests/regression-registry.js
- When user reports SecOps queue pollution, flaky verify scripts, or registry failures
Agent workflow (required order)
- Read
.cursor/skills/contract-first-governance/SKILL.md if the change touched contracts.
- Pre-flight (from
ict-governance-framework/):
npm run preflight:post-feature
- Start API if pre-flight warns port 4000 is down (separate terminal):
npm run server
Only one instance on port 4000. Restart after API route/service changes.
- Run full gate:
npm run verify:post-feature
-
Confirm success — all of:
12/12 passed (or current active suite count) in regression summary[VB-CP] Rollback attestation: printed with incidents_removed > 0 when suites create synthetic data- User confirms SecOps Incident Queue has no new synthetic rows (optional UI check)
-
On failure — fix root cause; do not weaken contracts. Re-run from step 2.
Faster paths
| Command | Use when |
|---|
npm run verify:registry:contracts | Jest contracts only (~3 suites, still checkpointed) |
npm run report:contract-coverage | Pillar enforcement KPI (active vs pending) |
npm run cleanup:verification-runs | Legacy test incidents left in console |
npm run verify:registry -- --skip-api | DB-only pass (skips G-B2/G-B3/assets smokes) |
npm run verify:registry -- --list | Show suite table |
Prerequisites checklist
| Requirement | Why |
|---|
DATABASE_URL in .env | All active suites hit Postgres |
| Local Postgres running | Connection refused → immediate fail |
npm install in ict-governance-framework | Jest + supertest |
npm run server on :4000 | verify:assets, verify:gb2, verify:gb3 |
| Superadmin login works | Default superadmin / Admin123! for API smokes |
| PowerShell on Windows | verify:gb3 runs Test-GitToCloudRecovery.ps1 |
| Schema scripts idempotent | Gate runs setup:* inside suites — missing tables fail loudly |
One-time / after pull
npm run setup:verification-checkpoint
npm run setup:managed-devices
What the gate runs
Auto-discovered Jest contracts (active when file has real it() tests, not only todos):
- identity, devices, secops — active today
- software, network, data, resilience — pending until todos are implemented
Legacy verify (manual list in LEGACY_SUITES): jit, break-glass, secops loop, calibration, assets, gb2, gb3, fair-risk, analytics, verify:casb-ingest (bulk path), cross-pillar invariants (QG-601)
New contract files are picked up automatically — no manual registry row for Jest pillars.
Cross-pillar invariants (last suite, before VB-CP rollback)
verify:cross-pillar asserts consistency across Identity, Devices, Software, and SecOps for the current VERIFICATION_RUN_ID:
- QG-601-1: high-risk CASB → SecOps incident
- QG-601-2: software
deviceId → managed device exists
- QG-601-3: non-compliant device + high-risk software → HIGH+ severity
- QG-601-4:
DEV-COMP-* incidents → device exists
- QG-601-5: no orphan high-risk CASB without incident or rollback audit
VB-CP rollback (expected behavior)
VERIFICATION_RUN_ID tags synthetic rows during the run- Operational tables restored;
governance_incident_ingest_log kept with rolled_back_at
- Signed ledger:
verification_checkpoint_ledger
If incidents remain in SecOps console after a green run:
npm run cleanup:verification-runs
Troubleshooting
| Symptom | Fix |
|---|
DATABASE_URL is required | Set .env; run from ict-governance-framework/ |
EADDRINUSE :4000 | Kill stale node server.js; start one API |
| G-B3 Phase 1 401 | API needs JWT-first auth in Test-GitToCloudRecovery.ps1 (not webhook-only) |
| G-B3 Phase 3 500 DR KPI | Restart API after drill-state-metrics.js changes; run setup:asset-dr-fields |
column ... does not exist | Run relevant npm run setup:* (e.g. setup:managed-devices) |
Jest uuid ESM error | jest.config.js moduleNameMapper → tests/contracts/_helpers/uuid-cjs-shim.js |
| Incidents in queue after green gate | npm run cleanup:verification-runs; ensure API passes verificationRunId on ingest |
| Registry validation fail | Add test:contracts:<pillar> to package.json; ensure @contract pillar:<name> header |
forceExit Jest warning | Expected — open pg pools in routers; harmless |
Adding a new suite to the gate
Jest contracts (automatic):
- Create
tests/contracts/<pillar>.contract.test.js with @contract pillar:<pillar>
- Add
test:contracts:<pillar> to package.json
- Write real
it() tests (not only it.todo) — suite becomes active in verify:post-feature
npm run validate:registry
Legacy verify scripts (manual): add an entry to LEGACY_SUITES in tests/regression-registry.js.
Key paths
| Area | Path |
|---|
| Registry | ict-governance-framework/tests/regression-registry.js |
| Runner | ict-governance-framework/scripts/run-regression-registry.js |
| VB-CP service | ict-governance-framework/services/verification-checkpoint.js |
| Pre-flight | ict-governance-framework/scripts/preflight-verify-post-feature.js |
Success criteria (agent)
Do not claim the gate is green without:
- Exit code 0 from
npm run verify:post-feature
- Regression summary shows all active suites PASS
- VB-CP rollback summary printed (unless
--no-checkpoint)
