125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# Audita Development Workflow
|
|
|
|
## Scope
|
|
|
|
This is the canonical contributor workflow for Audita maintainers and coding agents.
|
|
|
|
It defines:
|
|
- repository layout and boundaries;
|
|
- setup and test commands;
|
|
- expectations for code changes;
|
|
- how to add config, CLI, modules, validators, docs, and examples.
|
|
|
|
## Setup
|
|
|
|
Prerequisites:
|
|
- Go `1.24` or newer.
|
|
|
|
Common commands:
|
|
|
|
```sh
|
|
go test ./...
|
|
go build ./cmd/audita
|
|
```
|
|
|
|
## Repository Layout
|
|
|
|
Top-level areas:
|
|
- `cmd/audita`: executable entrypoint.
|
|
- `internal/cli`: command parsing and process/config command orchestration.
|
|
- `internal/core`: deterministic config/schema/normalization/chunking/output/diagnostics/reporting logic.
|
|
- `internal/framework`: runner orchestration, contracts, proposal generation/application, validators runtime, LLM runtime, response schemas.
|
|
- `internal/modules/*`: module-specific correction behavior.
|
|
- `internal/validators/*`: validator implementations, chains, and metadata.
|
|
- `internal/prompts`: embedded prompts and prompt metadata.
|
|
- `docs/`: canonical documentation.
|
|
- `examples/`: maintained copyable inputs/configs.
|
|
|
|
## Change Workflow
|
|
|
|
1. Confirm scope and behavior contract before editing.
|
|
2. Make focused changes in the appropriate ownership area.
|
|
3. Add or update tests for changed behavior.
|
|
4. Run targeted package tests for touched areas.
|
|
5. Run `go test ./...` for substantial changes.
|
|
6. Update docs/examples when external behavior changes.
|
|
|
|
## How To Add or Change Configuration
|
|
|
|
1. Add fields/defaults/validation under `internal/core/config`.
|
|
2. Apply source precedence correctly (defaults, file, env, CLI for `process`).
|
|
3. Ensure `config validate` remains file-only and `config print-effective` remains redacted.
|
|
4. Update tests in `internal/core/config` and related CLI tests.
|
|
5. Update [`docs/config.md`](../config.md) and relevant examples under `examples/`.
|
|
|
|
## How To Add or Change CLI Behavior
|
|
|
|
1. Implement parsing/wiring in `internal/cli`.
|
|
2. Keep stdout/stderr and exit behavior compatible unless intentional and documented.
|
|
3. Update CLI tests under `internal/cli` and integration tests under `cmd/audita`.
|
|
4. Update [`docs/cli.md`](../cli.md) and related integration docs.
|
|
|
|
## How To Add or Change Modules
|
|
|
|
1. Add or update one module package under `internal/modules/<module_key>`.
|
|
2. Keep module-specific prompt ownership in the module + `internal/prompts`.
|
|
3. Wire module registration/catalog resolution through framework/core module catalog code.
|
|
4. Verify replacement policy and validator chain selection.
|
|
5. Add/update module tests and proposal-generation tests.
|
|
6. Update internal docs when behavior/contracts change.
|
|
|
|
## How To Add or Change Validators
|
|
|
|
1. Implement validator behavior in `internal/validators` and shared runtime pieces in `internal/framework/validators` only when needed.
|
|
2. Preserve stable validator keys and decision semantics where already exposed.
|
|
3. Keep deterministic vs LLM-backed execution-class behavior explicit.
|
|
4. Add/update validator, chain, batching, and malformed-output tests.
|
|
5. Update validator documentation when external or developer-facing behavior changes.
|
|
|
|
## Documentation and Examples Expectations
|
|
|
|
- Keep one canonical home per topic (see [`docs/policy/documentation.md`](documentation.md)).
|
|
- Do not document future/unimplemented behavior outside `docs/roadmap/`.
|
|
- Keep command examples and config/examples in sync with current code.
|
|
- Keep examples secret-free and copyable.
|
|
|
|
## Practical Validation Checklist
|
|
|
|
Use this checklist for meaningful runtime-impacting changes:
|
|
|
|
1. Run core tests:
|
|
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
2. Verify config commands and examples:
|
|
|
|
```sh
|
|
go run ./cmd/audita config validate --config examples/minimal-config.yml
|
|
go run ./cmd/audita config validate --config examples/production-config.yml
|
|
go run ./cmd/audita config print-effective --config examples/minimal-config.yml
|
|
```
|
|
|
|
3. Re-check subprocess/runtime contract when touching CLI/process/report paths:
|
|
- `--output` success keeps stdout empty;
|
|
- no `--output` success writes transcript JSON to stdout;
|
|
- `--report-json` writes file output and is not written to stdout;
|
|
- failures return nonzero and include diagnostics path when available.
|
|
|
|
4. Re-check diagnostics/report/redaction when touching LLM, reporting, or diagnostics code:
|
|
- report schema metadata fields remain present;
|
|
- diagnostics artifact paths remain valid;
|
|
- configured secret values remain redacted in reports/diagnostics/errors.
|
|
|
|
5. Re-check output schema behavior when touching serialization/schema code:
|
|
- default `bare-segments` behavior remains correct unless intentionally changed;
|
|
- `audita-v1` behavior remains correct unless intentionally changed;
|
|
- unsupported schemas fail validation/resolve paths clearly.
|
|
|
|
## Commit Discipline
|
|
|
|
- Keep commits scoped and reviewable.
|
|
- Avoid mixing unrelated refactors with behavior changes.
|
|
- Use concise plain-English commit messages.
|