audita/docs/policy/development.md

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:

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 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 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).
• 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:

go test ./...

2. Verify config commands and examples:

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.