From 40e8b54d3b62266a4b0241cb4ffea24a99d5cc7f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 24 May 2026 00:47:27 +0000 Subject: [PATCH] Establish canonical documentation paths and update README links --- README.md | 10 +- docs/config.md | 149 +++++++++++++++++++++ docs/configuration.md | 150 +--------------------- docs/development.md | 34 +---- docs/integration/subprocess-operations.md | 97 +------------- docs/integrations/subprocess.md | 96 ++++++++++++++ docs/policy/development.md | 33 +++++ 7 files changed, 292 insertions(+), 277 deletions(-) create mode 100644 docs/config.md create mode 100644 docs/integrations/subprocess.md create mode 100644 docs/policy/development.md diff --git a/README.md b/README.md index 7f50361..2f9b64a 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ audita process transcript.json \ - stderr is human-readable diagnostics/errors. - successful runs remain quiet on stderr even when module warnings are recorded in report/diagnostics artifacts. -For subprocess orchestration guidance, see [`docs/subprocess-operations.md`](docs/subprocess-operations.md). +For subprocess orchestration guidance, see [`docs/integrations/subprocess.md`](docs/integrations/subprocess.md). ## Configuration @@ -150,7 +150,7 @@ audita config validate --config audita.yml audita config print-effective --config audita.yml ``` -For full config-file schema and examples, see [`docs/configuration.md`](docs/configuration.md). +For full config-file schema and examples, see [`docs/config.md`](docs/config.md). For output-schema details, see [`docs/architecture/output-schemas.md`](docs/architecture/output-schemas.md). For built-in validator keys and chain definitions, see [`docs/architecture/validators.md`](docs/architecture/validators.md). For embedded prompt assets and prompt metadata behavior, see [`docs/architecture/prompts.md`](docs/architecture/prompts.md). @@ -299,7 +299,7 @@ Optional external report output: ## Documentation - Architecture: [`docs/architecture.md`](docs/architecture.md) -- Diagnostics: [`docs/diagnostics.md`](docs/diagnostics.md) -- Structured LLM adapter: [`docs/structured-llm.md`](docs/structured-llm.md) -- Subprocess operations: [`docs/subprocess-operations.md`](docs/subprocess-operations.md) +- Diagnostics: [`docs/architecture/diagnostics.md`](docs/architecture/diagnostics.md) +- Structured LLM adapter: [`docs/architecture/structured-llm.md`](docs/architecture/structured-llm.md) +- Subprocess operations: [`docs/integrations/subprocess.md`](docs/integrations/subprocess.md) - Release checklist: [`docs/release-checklist.md`](docs/release-checklist.md) diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..f70d20d --- /dev/null +++ b/docs/config.md @@ -0,0 +1,149 @@ +# Audita Configuration + +## Scope +This document defines the supported versioned YAML configuration model and runtime precedence behavior. + +## Supported file version +Current supported config file version: +- `version: 1` + +Validation rules: +- missing `version` fails; +- unsupported version fails; +- unknown YAML fields fail (strict decoding). + +## Config path resolution +For `audita process` and `audita config print-effective`, path resolution order is: +1. `--config ` +2. `AUDITA_CONFIG` +3. `/usr/local/etc/audita/config.yml` (if present) +4. `/etc/audita/config.yml` (if present) + +Missing-path behavior: +- missing `--config` path is an error; +- missing `AUDITA_CONFIG` path is an error; +- missing both default paths is non-fatal. + +## Effective precedence +`audita process` effective precedence: +1. defaults +2. file config +3. environment overrides +4. CLI overrides + +`audita config print-effective` uses: +1. defaults +2. file config +3. environment overrides + +`audita config validate` intentionally uses file-only validation: +1. defaults +2. file config + +Environment overrides are not applied in `config validate`. + +## Supported top-level YAML fields +```yaml +version: 1 + +pipeline: + modules: [glossary, homophones, glossary, spoken_word, grammar] + +output: + schema: bare-segments + +llm: + proposal: + base_url: https://openrouter.ai/api/v1 + model: openrouter/google/gemma-4-31b-it + api_key_env: AUDITA_LLM_API_KEY + timeout: 120s + max_retries: 3 + validation: + base_url: https://openrouter.ai/api/v1 + model: openrouter/google/gemma-4-31b-it + api_key_env: AUDITA_VALIDATION_LLM_API_KEY + timeout: 120s + max_retries: 3 + +concurrency: + total_llm: 2 + proposal_llm: 2 + validation_llm: 1 + +chunking: + target_sections: 8 + max_section_tokens: 8192 + min_section_tokens: 2048 + +normalization: + max_segment_gap: 4s + ellipsis_gap: 3.5s + max_segment_duration: 60s + max_segment_tokens: 2048 + +thresholds: + glossary: 0.8 + homophones: 0.8 + spoken_word: 0.8 + grammar: 0.8 + +context: + description: "optional transcript background context" + +diagnostics: + work_dir: /tmp/audita + retention: auto +``` + +## Module and output-schema validation +`pipeline.modules` keys are validated against the built-in supported module catalog. + +Supported module keys: +- `glossary` +- `homophones` +- `spoken_word` +- `grammar` + +Repeated supported module keys are allowed. + +`output.schema` is validated against the built-in output schema catalog. + +Supported output schema keys: +- `bare-segments` +- `audita-v1` + +Unknown module keys and unknown output schema keys fail validation. + +## Duration field parsing +Duration-like fields support: +- numeric seconds (for example `120`, `3.5`) +- duration strings (for example `120s`, `2m`) + +LLM timeout duration strings must resolve to whole seconds. + +## Secret handling +Use `api_key_env` fields for secrets: +- `llm.proposal.api_key_env` +- `llm.validation.api_key_env` + +These fields store environment variable names, not secret values. + +Resolved secret values are redacted from: +- `audita config print-effective` output; +- diagnostics `effective-config.json`; +- report and diagnostics payloads. + +## Commands +Validate a file config: +```sh +audita config validate --config ./audita.yml +``` + +Print redacted effective config: +```sh +audita config print-effective --config ./audita.yml +``` + +## Compatibility notes +Legacy compatibility flags and environment aliases remain available where implemented, but the stable configuration surface is the versioned YAML model described above. diff --git a/docs/configuration.md b/docs/configuration.md index f70d20d..8d50bc9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,149 +1,5 @@ -# Audita Configuration +# Moved: Configuration Reference -## Scope -This document defines the supported versioned YAML configuration model and runtime precedence behavior. +The canonical configuration reference now lives at [`docs/config.md`](config.md). -## Supported file version -Current supported config file version: -- `version: 1` - -Validation rules: -- missing `version` fails; -- unsupported version fails; -- unknown YAML fields fail (strict decoding). - -## Config path resolution -For `audita process` and `audita config print-effective`, path resolution order is: -1. `--config ` -2. `AUDITA_CONFIG` -3. `/usr/local/etc/audita/config.yml` (if present) -4. `/etc/audita/config.yml` (if present) - -Missing-path behavior: -- missing `--config` path is an error; -- missing `AUDITA_CONFIG` path is an error; -- missing both default paths is non-fatal. - -## Effective precedence -`audita process` effective precedence: -1. defaults -2. file config -3. environment overrides -4. CLI overrides - -`audita config print-effective` uses: -1. defaults -2. file config -3. environment overrides - -`audita config validate` intentionally uses file-only validation: -1. defaults -2. file config - -Environment overrides are not applied in `config validate`. - -## Supported top-level YAML fields -```yaml -version: 1 - -pipeline: - modules: [glossary, homophones, glossary, spoken_word, grammar] - -output: - schema: bare-segments - -llm: - proposal: - base_url: https://openrouter.ai/api/v1 - model: openrouter/google/gemma-4-31b-it - api_key_env: AUDITA_LLM_API_KEY - timeout: 120s - max_retries: 3 - validation: - base_url: https://openrouter.ai/api/v1 - model: openrouter/google/gemma-4-31b-it - api_key_env: AUDITA_VALIDATION_LLM_API_KEY - timeout: 120s - max_retries: 3 - -concurrency: - total_llm: 2 - proposal_llm: 2 - validation_llm: 1 - -chunking: - target_sections: 8 - max_section_tokens: 8192 - min_section_tokens: 2048 - -normalization: - max_segment_gap: 4s - ellipsis_gap: 3.5s - max_segment_duration: 60s - max_segment_tokens: 2048 - -thresholds: - glossary: 0.8 - homophones: 0.8 - spoken_word: 0.8 - grammar: 0.8 - -context: - description: "optional transcript background context" - -diagnostics: - work_dir: /tmp/audita - retention: auto -``` - -## Module and output-schema validation -`pipeline.modules` keys are validated against the built-in supported module catalog. - -Supported module keys: -- `glossary` -- `homophones` -- `spoken_word` -- `grammar` - -Repeated supported module keys are allowed. - -`output.schema` is validated against the built-in output schema catalog. - -Supported output schema keys: -- `bare-segments` -- `audita-v1` - -Unknown module keys and unknown output schema keys fail validation. - -## Duration field parsing -Duration-like fields support: -- numeric seconds (for example `120`, `3.5`) -- duration strings (for example `120s`, `2m`) - -LLM timeout duration strings must resolve to whole seconds. - -## Secret handling -Use `api_key_env` fields for secrets: -- `llm.proposal.api_key_env` -- `llm.validation.api_key_env` - -These fields store environment variable names, not secret values. - -Resolved secret values are redacted from: -- `audita config print-effective` output; -- diagnostics `effective-config.json`; -- report and diagnostics payloads. - -## Commands -Validate a file config: -```sh -audita config validate --config ./audita.yml -``` - -Print redacted effective config: -```sh -audita config print-effective --config ./audita.yml -``` - -## Compatibility notes -Legacy compatibility flags and environment aliases remain available where implemented, but the stable configuration surface is the versioned YAML model described above. +This file is retained temporarily as a migration shim for older links. diff --git a/docs/development.md b/docs/development.md index 614b211..2cf1d87 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,33 +1,5 @@ -# Audita Development Workflow +# Moved: Development Workflow -## Scope -This document defines the canonical contributor workflow and engineering conventions for this repository. +The canonical contributor workflow now lives at [`docs/policy/development.md`](policy/development.md). -## 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. - -## 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. - -## 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. - -## 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. - -## Commit discipline -- Keep commits scoped and reviewable. -- Avoid mixing unrelated refactors with behavior changes. -- Use clear plain-English commit messages. +This file is retained temporarily as a migration shim for older links. diff --git a/docs/integration/subprocess-operations.md b/docs/integration/subprocess-operations.md index d94aeef..d7bd17f 100644 --- a/docs/integration/subprocess-operations.md +++ b/docs/integration/subprocess-operations.md @@ -1,96 +1,5 @@ -# Audita Subprocess Operations +# Moved: Subprocess Integration -This document describes how parent processes should invoke `audita process` safely in production orchestration. +The canonical subprocess integration guide now lives at [`docs/integrations/subprocess.md`](../integrations/subprocess.md). -## Recommended command form - -Use explicit file outputs for orchestrated runs: - -```sh -audita process \ - --transcript-description "Brief context that may help resolve ambiguous terms." \ - --glossary \ - --output \ - --report-json -``` - -Additional flags that may be situationally appropriate: -- `--config ` to select an explicit versioned config file. -- `--output-schema ` to select transcript output shape. -- `--work-dir ` to control diagnostics location. -- `--work-dir-retention ` to control retained run directories. -- `--total-llm-concurrency`, `--proposal-llm-concurrency`, and `--validation-llm-concurrency` when orchestration needs to set explicit LLM throughput controls. -- `--modules ...` only when intentionally overriding the default sequence. - -For config-driven orchestration, validate config files in CI/preflight: - -```sh -audita config validate --config -``` - -## Stdout behavior - -- With `--output`: stdout is expected to be empty on success. -- Without `--output`: stdout contains transcript JSON only on success. -- Report JSON is never written to stdout. - -## Stderr behavior - -- Success path should be quiet or minimal human-readable logs. -- Failure path writes concise human-readable errors. -- When a diagnostics run directory exists, failure stderr includes its path. -- Prompt/response diagnostic payloads are not streamed to stderr. - -## Output file behavior - -- `--output` writes transcript JSON in the selected output schema to the provided path. -- Output write failures return nonzero and surface actionable errors. -- The command does not silently ignore output write errors. - -## Report JSON behavior - -- `--report-json` writes a machine-readable process report to the requested path. -- Run-directory `report.json` is written independently under diagnostics. -- Best-effort failure reports are emitted when possible without masking the primary failure. -- Report write failures return nonzero with clear stderr messaging. -- Report diagnostics metadata references run-directory artifacts including utilization diagnostics and correction ledger paths when available. - -## Diagnostics directory behavior - -- Each run creates (when possible) a per-run diagnostics directory. -- Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, and `error.log` on failure. -- Failed runs retain diagnostics. -- Under `auto` retention, successful runs with skipped/rejected corrections are retained; clean successful runs may be removed. - -## Exit codes - -- `0`: success. -- Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors). - -Treat any nonzero as a failed subprocess invocation. - -## Timeout and cancellation - -- Runtime operations propagate context cancellation and request timeouts through LLM/scheduler paths. -- On cancellation or timeout, the process exits nonzero and should not hang. -- If diagnostics were initialized before failure, failure artifacts remain available for debugging. - -## Secret redaction expectations - -API keys and configured secret values are redacted from: -- reports (`--report-json` and run-dir `report.json`); -- diagnostics artifacts (including effective config and LLM interaction artifacts); -- surfaced adapter/runtime errors; -- test fixtures and regression outputs. - -Parent-process logs should still avoid printing raw environment variables. - -## Parent-process pipe guidance - -To avoid deadlocks in orchestrators: -- always read both stdout and stderr concurrently when invoking as a subprocess; -- prefer file outputs (`--output`, `--report-json`) for machine workflows; -- treat stderr as human-readable diagnostics, not structured data; -- parse structured results from output/report files. - -For Go callers, prefer `exec.CommandContext` with explicit timeout/cancellation and buffered/streamed readers for both pipes. +This file is retained temporarily as a migration shim for older links. diff --git a/docs/integrations/subprocess.md b/docs/integrations/subprocess.md new file mode 100644 index 0000000..d94aeef --- /dev/null +++ b/docs/integrations/subprocess.md @@ -0,0 +1,96 @@ +# Audita Subprocess Operations + +This document describes how parent processes should invoke `audita process` safely in production orchestration. + +## Recommended command form + +Use explicit file outputs for orchestrated runs: + +```sh +audita process \ + --transcript-description "Brief context that may help resolve ambiguous terms." \ + --glossary \ + --output \ + --report-json +``` + +Additional flags that may be situationally appropriate: +- `--config ` to select an explicit versioned config file. +- `--output-schema ` to select transcript output shape. +- `--work-dir ` to control diagnostics location. +- `--work-dir-retention ` to control retained run directories. +- `--total-llm-concurrency`, `--proposal-llm-concurrency`, and `--validation-llm-concurrency` when orchestration needs to set explicit LLM throughput controls. +- `--modules ...` only when intentionally overriding the default sequence. + +For config-driven orchestration, validate config files in CI/preflight: + +```sh +audita config validate --config +``` + +## Stdout behavior + +- With `--output`: stdout is expected to be empty on success. +- Without `--output`: stdout contains transcript JSON only on success. +- Report JSON is never written to stdout. + +## Stderr behavior + +- Success path should be quiet or minimal human-readable logs. +- Failure path writes concise human-readable errors. +- When a diagnostics run directory exists, failure stderr includes its path. +- Prompt/response diagnostic payloads are not streamed to stderr. + +## Output file behavior + +- `--output` writes transcript JSON in the selected output schema to the provided path. +- Output write failures return nonzero and surface actionable errors. +- The command does not silently ignore output write errors. + +## Report JSON behavior + +- `--report-json` writes a machine-readable process report to the requested path. +- Run-directory `report.json` is written independently under diagnostics. +- Best-effort failure reports are emitted when possible without masking the primary failure. +- Report write failures return nonzero with clear stderr messaging. +- Report diagnostics metadata references run-directory artifacts including utilization diagnostics and correction ledger paths when available. + +## Diagnostics directory behavior + +- Each run creates (when possible) a per-run diagnostics directory. +- Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, and `error.log` on failure. +- Failed runs retain diagnostics. +- Under `auto` retention, successful runs with skipped/rejected corrections are retained; clean successful runs may be removed. + +## Exit codes + +- `0`: success. +- Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors). + +Treat any nonzero as a failed subprocess invocation. + +## Timeout and cancellation + +- Runtime operations propagate context cancellation and request timeouts through LLM/scheduler paths. +- On cancellation or timeout, the process exits nonzero and should not hang. +- If diagnostics were initialized before failure, failure artifacts remain available for debugging. + +## Secret redaction expectations + +API keys and configured secret values are redacted from: +- reports (`--report-json` and run-dir `report.json`); +- diagnostics artifacts (including effective config and LLM interaction artifacts); +- surfaced adapter/runtime errors; +- test fixtures and regression outputs. + +Parent-process logs should still avoid printing raw environment variables. + +## Parent-process pipe guidance + +To avoid deadlocks in orchestrators: +- always read both stdout and stderr concurrently when invoking as a subprocess; +- prefer file outputs (`--output`, `--report-json`) for machine workflows; +- treat stderr as human-readable diagnostics, not structured data; +- parse structured results from output/report files. + +For Go callers, prefer `exec.CommandContext` with explicit timeout/cancellation and buffered/streamed readers for both pipes. diff --git a/docs/policy/development.md b/docs/policy/development.md new file mode 100644 index 0000000..614b211 --- /dev/null +++ b/docs/policy/development.md @@ -0,0 +1,33 @@ +# 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. + +## 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. + +## 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. + +## 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. + +## Commit discipline +- Keep commits scoped and reviewable. +- Avoid mixing unrelated refactors with behavior changes. +- Use clear plain-English commit messages.