Extending Attest
CDX owns shared surfaces, runner adapters, validators, gates and report engines. Consumer repositories own their plans, datasets, registrations and product scenarios. Paths such as config/ below are relative to a consumer's Attest product root. The product plan defines current delivery scope; this guide explains extension ownership.
Add a plan
- Add a typed JSON plan under
config/plans/. - Reference one dataset profile from
config/datasets/. - Define suites, tests, checkpoints, mandatory scope, gate policy, and report template in that plan.
- Register the executable suite in
registry/modules/andmanifests/. - Add contract, gate, integrity, and runner tests.
Do not duplicate plan metadata in the test, dashboard, or PDF renderer.
Add checkpoints and evidence
Each UI checkpoint requires:
- stable checkpoint ID
- immutable execution-local evidence ID such as
EV-014 - title and expected behavior
- actor
- mandatory flag
- verification categories
- evidence requirement
The Patrol helper records observed behavior and capture time. The internal collector preserves and hashes the screenshot; the immutable evidence context is carried by the manifest and report. Generic renderers do not contain test-specific names.
Add a test surface
- Add or reuse a
QualificationSurfaceandQualificationReportTemplate. - Register its applicable report sections in
qualification_report_template.dart. - Implement a runner adapter that returns canonical suite, test, checkpoint, assertion, and evidence data.
- Add only meaningful surface metrics.
- Test missing, corrupt, failed, blocked, skipped, and clean-success paths.
Use the existing API, action/integration, UI and performance surfaces where they fit. A report mapping alone does not implement a runner or evidence collector; advertise a surface only after execution and evidence are verified.
Dataset profiles
A dataset profile owns ID, version, seed version, initialization strategy, isolation mode, baseline count, generated count/prefix, and optional checksum. Reset and initialization must finish before the dataset gate can pass.
Gate changes
Gate policy belongs in plan configuration. Gate evaluation belongs in qualification_gate_evaluator.dart. The dashboard and report may display gate output but must never calculate it independently.