# Gavel Documentation

Version: **0.12.1** (see [CHANGELOG.md](../CHANGELOG.md))

Index for scripts, templates, and companion workflows. For install and first run, start at [README.md](../README.md).

## Start here

| Doc | Purpose | Audience |
|-----|---------|----------|
| [README.md](../README.md) | Install, core commands, feature grid | New users |
| [QUICKSTART.md](../QUICKSTART.md) | First session: audit → heal → write | QA engineers |
| [ENTERPRISE.md](ENTERPRISE.md) | CI gate, SARIF, trust criteria, data handling | Platform / staff eng |
| [CLI_MATRIX.md](CLI_MATRIX.md) | Which commands are real CLI vs agent-only | Platform / contributors |
| [AGENTS_AND_SKILLS.md](AGENTS_AND_SKILLS.md) | Complete agent and skill inventory, scopes, limits, and job autonomy | QA, platform, architects |
| [AGENTS.md](../AGENTS.md) | Universal QA rules | All IDE adapters |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Two-repo design, browser-first authoring principle | Contributors, architects |
| [solicitud-habilitacion-gavel-azure-devops.md](solicitud-habilitacion-gavel-azure-devops.md) | Cross-team intake and approvals for the Azure DevOps PR reviewer pilot | Business, QA, DevOps, security, architects |
| [BAILIFF.md](BAILIFF.md) | Sibling QA-workflow repo (planning only) | Architects |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Verify gate, model tiers, budgets | Contributors |
| [fixtures/corpus/README.md](../fixtures/corpus/README.md) | Corpus label + precision contract (v0.8) | Contributors |
| [rules/brittle-assert.md](rules/brittle-assert.md) | Heuristic contract: prose equality assertions | Contributors / Tier-R |
| [rules/assert-drop.md](rules/assert-drop.md) | Diff harness: assertion deletion / early-return / strength downgrade | Contributors / Tier-B |
| [companion/README.md](../companion/README.md) | Optional CI/env/hub/closure skills | Teams needing extras |

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/cli.js` | Unified CLI (`gavel <command>`) |
| `scripts/self-check.js` | Constitution violation scan (`--json`, `--format sarif`) |
| `scripts/audit-report.js` | Ranked audit + suite health (`--with-self-check`, `--audit-format`) |
| `scripts/to-sarif.js` | SARIF 2.1.0 serialization |
| `scripts/refactor-score.js` | Before/after line count + violation delta |
| `scripts/affected-tests.js` | Affected spec discovery + `--tag` |
| `scripts/extract-tags.js` | Multi-framework tag extraction |
| `scripts/analyze-ci.js` | Parse CI report, cluster, correlate commits |
| `scripts/adoption-scan.js` | Remediation-helper / fixture adoption gaps (`gavel adoption`, report-only) |
| `scripts/flakiness.js` | Per-test flakiness score from CI history (`gavel flakiness`, report-only) |
| `scripts/audit-autofix.js` | Safe dead code removal (dry-run default) |
| `scripts/verify-docs.js` | Doc drift guardrail (runs in `npm run verify`) |
| `scripts/verify-corpus-precision.js` | Heuristic corpus precision (`fixtures/corpus/`) |
| `scripts/verify-diff-corpus-precision.js` | Diff-corpus precision (`fixtures/self-check/diff/`) |

### Report parsers

| Format | Parser |
|--------|--------|
| JUnit XML | `scripts/parsers/junit.js` |
| Allure results dir | `scripts/parsers/allure.js` |
| Playwright JSON | `scripts/parsers/playwright.js` |
| Playwright HTML dir | `scripts/parsers/playwright-html.js` |
| Cypress JSON | `scripts/parsers/cypress.js` |
| Cucumber JSON | `scripts/parsers/cucumber.js` |
| Auto-detect | `scripts/parsers/index.js` |

### CI templates

| Template | Purpose |
|----------|---------|
| [templates/github-actions/gavel-verify.yml](../templates/github-actions/gavel-verify.yml) | Verify gate for adapter forks |
| [templates/github-actions/gavel-audit-sarif.yml](../templates/github-actions/gavel-audit-sarif.yml) | Consumer audit → SARIF → Code Scanning |
| [templates/gitlab-ci/gavel-self-check.yml](../templates/gitlab-ci/gavel-self-check.yml) | Self-check on target automation repo |
| [templates/apply-safe-workflow.md](../templates/apply-safe-workflow.md) | Orchestrator → refactor handoff |

### Example commands

```bash
npx gavel audit --format sarif
npx gavel self-check --format sarif
node scripts/audit-report.js ../my-automation-repo --with-self-check --audit-format
node scripts/refactor-score.js ../my-automation-repo
node scripts/analyze-ci.js playwright-report/ --envelope --project MySuite
node scripts/affected-tests.js ../my-repo --tag smoke
```

## Skills and agents

- **Core skills:** `skills/*/SKILL.md` (31 skills — in default plugin manifest)
- **Companion skills:** `companion/skills/*/SKILL.md` (4 optional workflows)
- **Agents:** `agents/*.md` — workflow specialists
- **Templates:** `templates/result-envelope.md` — completion contract

See [AGENTS_AND_SKILLS.md](AGENTS_AND_SKILLS.md) for the full catalog and [CLI_MATRIX.md](CLI_MATRIX.md) before treating a skill name as a CI binary.

Run `npm run verify` from the gavel package root before release.