# dsolisp/gavel architecture

> Architecture diagram of the GitHub repository dsolisp/gavel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dsolisp/gavel
- Repository: https://github.com/dsolisp/gavel

## Overview

#### 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/`

Main entry points: [`scripts/cli.js`](https://github.com/dsolisp/gavel/blob/main/scripts/cli.js) (Unified CLI), [`scripts/self-check.js`](https://github.com/dsolisp/gavel/blob/main/scripts/self-check.js) (Constitution scanner), [`scripts/audit-report.js`](https://github.com/dsolisp/gavel/blob/main/scripts/audit-report.js) (Audit report), [`scripts/analyze-ci.js`](https://github.com/dsolisp/gavel/blob/main/scripts/analyze-ci.js) (CI failure analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Integration"]
  node_cli{{"Unified CLI<br/>command router<br/>[cli.js]"}}
  node_agent_skills["Agent skills<br/>agent instructions<br/>[SKILL.md]"]
  node_plugin_manifest["Plugin manifest<br/>IDE plugin asset<br/>[plugin.yaml]"]
  node_runtime_hook["Runtime hook<br/>IDE hook<br/>[gavel-runtime.js]"]
end

subgraph group_analysis["Analysis Pipelines"]
  node_constitution_scanner["Constitution scanner<br/>static QA scanner<br/>[self-check.js]"]
  node_review["Review analysis<br/>review command<br/>[review.js]"]
  node_audit["Audit report<br/>structural audit<br/>[audit-report.js]"]
  node_autofix["Audit autofix<br/>safe refactoring<br/>[audit-autofix.js]"]
  node_refactor_score["Refactor scoring<br/>change evidence<br/>[refactor-score.js]"]
  node_impact["Affected tests<br/>impact analysis<br/>[affected-tests.js]"]
  node_area_map["Area map tooling<br/>topology model<br/>[area-map.js]"]
  node_ci_analysis["CI failure analysis<br/>failure intelligence<br/>[analyze-ci.js]"]
  node_report_parsers["Report adapters<br/>format parsers<br/>[index.js]"]
end

subgraph group_contracts["Contracts &amp; Policy"]
  node_result_schema["Result envelope schema<br/>JSON Schema"]
  node_config_schema["Config &amp; baseline schemas<br/>JSON Schema"]
  node_sarif["SARIF exporter<br/>CI report exporter<br/>[to-sarif.js]"]
end

subgraph group_delivery["Delivery &amp; Verification"]
  node_boundary_check["Bailiff boundary check<br/>scope guard<br/>[verify-boundary.js]"]
  node_package["npm package<br/>distribution manifest<br/>[package.json]"]
  node_ci_verify["GitHub verification<br/>CI workflow<br/>[gavel-verify.yml]"]
  node_fixtures[("External fixtures<br/>automation repositories")]
end

node_agent_skills -.->|"guides use of"| node_cli
node_plugin_manifest -->|"packages"| node_agent_skills
node_runtime_hook -->|"activates"| node_cli
node_cli -->|"runs"| node_constitution_scanner
node_cli -->|"runs"| node_audit
node_cli -->|"runs"| node_impact
node_cli -->|"runs"| node_ci_analysis
node_review -->|"uses findings"| node_constitution_scanner
node_constitution_scanner -->|"supplies violations"| node_audit
node_audit -->|"identifies candidates"| node_autofix
node_autofix -->|"requires evidence"| node_refactor_score
node_area_map -->|"provides topology"| node_impact
node_report_parsers -->|"normalizes reports"| node_ci_analysis
node_constitution_scanner -->|"emits envelope"| node_result_schema
node_audit -->|"emits envelope"| node_result_schema
node_ci_analysis -->|"emits envelope"| node_result_schema
node_result_schema -->|"converts"| node_sarif
node_config_schema -.->|"validates config"| node_constitution_scanner
node_fixtures -.->|"test targets"| node_constitution_scanner
node_fixtures -.->|"report inputs"| node_ci_analysis
node_ci_verify -->|"runs"| node_boundary_check
node_ci_verify -->|"verifies release assets"| node_package

click node_cli "https://github.com/dsolisp/gavel/blob/main/scripts/cli.js"
click node_agent_skills "https://github.com/dsolisp/gavel/blob/main/skills/gavel/SKILL.md"
click node_plugin_manifest "https://github.com/dsolisp/gavel/blob/main/plugin.yaml"
click node_runtime_hook "https://github.com/dsolisp/gavel/blob/main/hooks/gavel-runtime.js"
click node_constitution_scanner "https://github.com/dsolisp/gavel/blob/main/scripts/self-check.js"
click node_review "https://github.com/dsolisp/gavel/blob/main/scripts/review.js"
click node_audit "https://github.com/dsolisp/gavel/blob/main/scripts/audit-report.js"
click node_autofix "https://github.com/dsolisp/gavel/blob/main/scripts/audit-autofix.js"
click node_refactor_score "https://github.com/dsolisp/gavel/blob/main/scripts/refactor-score.js"
click node_impact "https://github.com/dsolisp/gavel/blob/main/scripts/affected-tests.js"
click node_area_map "https://github.com/dsolisp/gavel/blob/main/scripts/area-map.js"
click node_ci_analysis "https://github.com/dsolisp/gavel/blob/main/scripts/analyze-ci.js"
click node_report_parsers "https://github.com/dsolisp/gavel/blob/main/scripts/parsers/index.js"
click node_result_schema "https://github.com/dsolisp/gavel/blob/main/schemas/result-envelope.schema.json"
click node_config_schema "https://github.com/dsolisp/gavel/blob/main/schemas/gavel-config.schema.json"
click node_sarif "https://github.com/dsolisp/gavel/blob/main/scripts/to-sarif.js"
click node_boundary_check "https://github.com/dsolisp/gavel/blob/main/scripts/verify-boundary.js"
click node_package "https://github.com/dsolisp/gavel/blob/main/package.json"
click node_ci_verify "https://github.com/dsolisp/gavel/blob/main/.github/workflows/gavel-verify.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_agent_skills,node_plugin_manifest,node_runtime_hook toneBlue
class node_constitution_scanner,node_review,node_audit,node_autofix,node_refactor_score,node_impact,node_area_map,node_ci_analysis,node_report_parsers toneAmber
class node_result_schema,node_config_schema,node_sarif toneMint
class node_boundary_check,node_package,node_ci_verify,node_fixtures toneRose
```

## Components

### Entry & Integration

- [Unified CLI](https://github.com/dsolisp/gavel/blob/main/scripts/cli.js): command router · Dispatches audit, review, detection, CI, and impact commands. · `scripts/cli.js`
- [Agent skills](https://github.com/dsolisp/gavel/blob/main/skills/gavel/SKILL.md): agent instructions · `skills/gavel/SKILL.md`
- [Plugin manifest](https://github.com/dsolisp/gavel/blob/main/plugin.yaml): IDE plugin asset · `plugin.yaml`
- [Runtime hook](https://github.com/dsolisp/gavel/blob/main/hooks/gavel-runtime.js): IDE hook · `hooks/gavel-runtime.js`

### Analysis Pipelines

- [Constitution scanner](https://github.com/dsolisp/gavel/blob/main/scripts/self-check.js): static QA scanner · Detects cross-framework test-governance violations. · `scripts/self-check.js`
- [Review analysis](https://github.com/dsolisp/gavel/blob/main/scripts/review.js): review command · `scripts/review.js`
- [Audit report](https://github.com/dsolisp/gavel/blob/main/scripts/audit-report.js): structural audit · Combines findings, dead-code evidence, suite health, and area ranking. · `scripts/audit-report.js`
- [Audit autofix](https://github.com/dsolisp/gavel/blob/main/scripts/audit-autofix.js): safe refactoring · `scripts/audit-autofix.js`
- [Refactor scoring](https://github.com/dsolisp/gavel/blob/main/scripts/refactor-score.js): change evidence · `scripts/refactor-score.js`
- [Affected tests](https://github.com/dsolisp/gavel/blob/main/scripts/affected-tests.js): impact analysis · Resolves tests affected by changes transitively. · `scripts/affected-tests.js`
- [Area map tooling](https://github.com/dsolisp/gavel/blob/main/scripts/area-map.js): topology model · Generates and validates repository area boundaries. · `scripts/area-map.js`
- [CI failure analysis](https://github.com/dsolisp/gavel/blob/main/scripts/analyze-ci.js): failure intelligence · Normalizes external reports for clustering and flake diagnosis. · `scripts/analyze-ci.js`
- [Report adapters](https://github.com/dsolisp/gavel/blob/main/scripts/parsers/index.js): format parsers · Ingests JUnit, Allure, Playwright, Cypress, and Cucumber reports. · `scripts/parsers/index.js`

### Contracts & Policy

- [Result envelope schema](https://github.com/dsolisp/gavel/blob/main/schemas/result-envelope.schema.json): JSON Schema · Machine contract for piped agent and script results. · `schemas/result-envelope.schema.json`
- [Config & baseline schemas](https://github.com/dsolisp/gavel/blob/main/schemas/gavel-config.schema.json): JSON Schema · Validates Gavel configuration and baselines. · `schemas/gavel-config.schema.json`
- [SARIF exporter](https://github.com/dsolisp/gavel/blob/main/scripts/to-sarif.js): CI report exporter · `scripts/to-sarif.js`

### Delivery & Verification

- [Bailiff boundary check](https://github.com/dsolisp/gavel/blob/main/scripts/verify-boundary.js): scope guard · Mechanically prevents Bailiff material becoming a runtime dependency. · `scripts/verify-boundary.js`
- [npm package](https://github.com/dsolisp/gavel/blob/main/package.json): distribution manifest · `package.json`
- [GitHub verification](https://github.com/dsolisp/gavel/blob/main/.github/workflows/gavel-verify.yml): CI workflow · Verifies Gavel governance and distribution assets. · `.github/workflows/gavel-verify.yml`
- **External fixtures**: automation repositories · Representative target repositories and report inputs.

## Connections

- Agent skills → Unified CLI: guides use of
- Plugin manifest → Agent skills: packages
- Runtime hook → Unified CLI: activates
- Unified CLI → Constitution scanner: runs
- Unified CLI → Audit report: runs
- Unified CLI → Affected tests: runs
- Unified CLI → CI failure analysis: runs
- Review analysis → Constitution scanner: uses findings
- Constitution scanner → Audit report: supplies violations
- Audit report → Audit autofix: identifies candidates
- Audit autofix → Refactor scoring: requires evidence
- Area map tooling → Affected tests: provides topology
- Report adapters → CI failure analysis: normalizes reports
- Constitution scanner → Result envelope schema: emits envelope
- Audit report → Result envelope schema: emits envelope
- CI failure analysis → Result envelope schema: emits envelope
- Result envelope schema → SARIF exporter: converts
- Config & baseline schemas → Constitution scanner: validates config
- External fixtures → Constitution scanner: test targets
- External fixtures → CI failure analysis: report inputs
- GitHub verification → Bailiff boundary check: runs
- GitHub verification → npm package: verifies release assets