dsolisp/gavel

Purpose and Entry Points

Gavel is a Node.js, agent-oriented QA discipline layer for test-automation repositories. It statically audits multi-framework test code, produces CI-consumable reports, and ships skills/plugins for many AI IDEs. Primary executable entry point: scripts/cli.js; direct CI gates include scripts/self-check.js, scripts/audit-report.js, and scripts/to-sarif.js. Agent-facing behavior is defined through skills/gavel/SKILL.md, specialized skills under skills/, and the shared rules in AGENTS.md.

Command Dispatch and Agent Integration

scripts/cli.js is the unified command router for audit, review, detection, CI analysis, affected-test discovery, and companion commands. IDE integrations package the same Gavel instruction set in platform-specific plugin manifests, while hooks activate/configure runtime behavior.

• scripts/cli.js

• plugin.yaml

• hooks/gavel-runtime.js

Static Constitution Enforcement

The core quality boundary is the multi-framework constitution scanner. It detects violations such as selector leakage, manual waits, assertion leakage, skipped tests, direct page-object construction, hardcoded environment values, and unsafe suppressions. It consumes a target automation repository and config/suppression context, then emits findings suitable for human review or downstream report formats.

• scripts/self-check.js

• scripts/review.js

• docs/rules/manual-wait.md is not present; rule documentation available includes docs/rules/brittle-assert.md

Audit, Dead-Code, and Safe Refactoring Pipeline

Audit combines constitution findings with structural analysis: unused pages/locators/factories, suite-health counts, area ranking, and autofix candidates. The refactoring path scores changes and can identify safe dead-code removal based on evidence; this is deliberately separate from general-purpose code modification.

• scripts/audit-report.js

• scripts/audit-autofix.js

• scripts/refactor-score.js

Machine Contracts and CI Output

Gavel’s automation boundary is schema-backed output. Result envelopes support piping between agents and scripts; SARIF supports GitHub Code Scanning and other CI dashboards. Configuration, baselines, area maps, and corpus labels are validated against JSON schemas rather than treated as implicit conventions.

• schemas/result-envelope.schema.json

• schemas/gavel-config.schema.json

• schemas/gavel-baseline.schema.json

• scripts/to-sarif.js

• scripts/validate-envelope.js

Test Impact, Area Modeling, and Evidence

Change-oriented analysis maps code/test structure into areas, resolves affected tests transitively, and supports evidence gates before a task is declared complete. Area maps can be generated and manually validated, creating a boundary between repository topology and policy decisions.

• scripts/affected-tests.js

• scripts/generate-area-map.js

• scripts/area-map.js

• scripts/validate-area-map.js

CI Failure Intelligence

CI analysis ingests external report artifacts through format adapters, normalizes failures, clusters related failures, and supports flake-oriented diagnosis. Supported report boundaries include JUnit XML, Allure JSON, Playwright/HTML reports, Cypress, and Cucumber.

• scripts/analyze-ci.js

• scripts/cluster-failures.js

• scripts/flakiness.js

• scripts/parsers/index.js

Distribution, Validation, and Scope Boundary

The repository distributes Gavel as npm/plugin assets and verifies its own governance in GitHub Actions. The Gavel/Bailiff separation is mechanically guarded, with Bailiff-related material documented rather than embedded as a runtime dependency. Fixtures provide representative external automation repositories and report inputs for regression validation.

• package.json

• .github/workflows/gavel-verify.yml

• scripts/verify-boundary.js

• docs/ARCHITECTURE.md

• fixtures/sample-repos/