# Neith QA Developer Guide

This guide is for contributors extending `@neith/qa`.

## Package Layout

```text
libs/neith/qa/
  src/
    code-quality/
      *.ts         deterministic auditors and certification formatters
      *.spec.ts    fixture-based and repo-backed verification
    doc-quality/
      *.ts         generic documentation analyzers
      *.spec.ts    verification for those analyzers
    types.ts       shared report, issue, and summary types
    index.ts       package export surface
  package.json     package metadata and QA utility scripts
  project.json     Nx targets
```

## Development Rules

- Auditors must be deterministic and file-system based. Avoid network I/O and
  non-reproducible environment assumptions.
- Treat Phase 52 completion criteria as certifiable claims. The auditor should
  prove the claim, not merely restate it.
- Every new gate needs both a negative fixture test and a repo-backed
  certification test.
- Published certification markdown under `docs/domains/neith/` must stay in sync
  with the generated report format.

## Adding A Certification Gate

1. Create the auditor in `src/code-quality/`.
2. Add the exported report and issue types in `src/types.ts`.
3. Export the module from `src/code-quality/index.ts`.
4. Add a Vitest spec that checks an incomplete fixture and the real repo.
5. Publish the certification markdown in `docs/domains/neith/`.
6. Link the certification from the Neith docs hubs and update the relevant TODO
   entry.

## Verification Commands

```bash
pnpm nx run @neith/qa:typecheck
pnpm nx run @neith/qa:lint
pnpm nx run @neith/qa:test
pnpm nx run @neith/qa:sbom
```

Run `sbom` whenever your changes affect the committed Phase 52 SBOM artifacts.

## Working With Documentation Gates

- Use explicit path constants for required docs so the scope is auditable.
- Check for both file presence and meaningful section markers.
- Verify links from the standalone domain index and Oshun-local references so
  the docs are discoverable, not just present.
- Keep certification prose short and evidence-led. The generated markdown is a
  ledger, not a marketing page.
