Consolidate development policy docs and remove legacy documentation paths

docs/policy/development.md

@@ -1,33 +1,124 @@
 # Audita Development Workflow
 
 ## Scope
-This document defines the canonical contributor workflow and engineering conventions for this repository.
 
-## Workflow
-1. Start from a clean understanding of scope and constraints.
-2. Make focused changes that preserve existing public behavior unless behavior change is explicitly intended.
-3. Run targeted tests for touched packages.
-4. Run `go test ./...` before finalizing substantial changes.
-5. Update affected documentation so it describes current behavior only.
+This is the canonical contributor workflow for Audita maintainers and coding agents.
 
-## Engineering conventions
-- Keep module packages separate: `glossary`, `homophones`, `spoken_word`, `grammar`.
-- Prefer narrow shared helpers and catalogs over broad abstractions.
-- Preserve diagnostics artifact naming and report field contracts unless intentionally changed.
-- Preserve CLI/config precedence semantics unless intentionally changed.
-- Treat stable validator keys, prompt identifiers, and output-schema keys as contract surfaces.
+It defines:
+- repository layout and boundaries;
+- setup and test commands;
+- expectations for code changes;
+- how to add config, CLI, modules, validators, docs, and examples.
 
-## Configuration and runtime expectations
-- `audita process` precedence is defaults -> file -> env -> CLI.
-- `audita config validate` validates file config merged onto defaults only.
-- `audita config print-effective` includes environment overrides and prints redacted JSON.
+## Setup
 
-## Testing expectations
-- Add tests for new behavior and for bug fixes.
-- Keep deterministic fixtures stable.
-- Do not reduce existing parity, release-fixture, subprocess, or module-specific coverage without equivalent replacement.
+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
 
-## Commit discipline
 - Keep commits scoped and reviewable.
 - Avoid mixing unrelated refactors with behavior changes.
-- Use clear plain-English commit messages.
+- Use concise plain-English commit messages.