audita/docs/roadmap/documentation.md

Documentation Roadmap

Purpose

This roadmap defines the work required to bring Audita documentation into compliance with docs/policy/documentation.md and the implemented architecture described by docs/policy/architecture.md.

This is an implementation plan for future documentation cleanup. It does not rewrite the main documentation. Future implementation passes should document only current behavior outside docs/roadmap/, keep planned or unimplemented work in roadmap files, and verify claims against repository code and tests rather than stale documentation.

Repository Documentation Inventory

• README.md: keep and rewrite. It should remain the project orientation and quickstart, but it currently carries too much reference material and includes stale links such as docs/diagnostics.md, docs/structured-llm.md, and docs/subprocess-operations.md.
• docs/policy/documentation.md: keep and lightly update only if needed. It is the canonical documentation policy.
• docs/policy/architecture.md: keep and lightly verify after the migration. It is the canonical architecture policy for developers and coding agents.
• docs/development.md: move and rewrite as docs/policy/development.md. Contributor workflow belongs under docs/policy/.
• docs/configuration.md: move and rewrite as docs/config.md. Configuration reference belongs at the canonical config path.
• docs/architecture.md: merge or delete after the internal docs are created. Its useful content should become an internal overview or links to canonical internal docs.
• docs/architecture/architecture.md: split and rewrite into docs/internal/overview.md and docs/internal/pipeline.md.
• docs/architecture/public-contract.md: split across docs/cli.md, docs/config.md, docs/operations.md, and integration docs where applicable.
• docs/architecture/diagnostics.md: split across docs/operations.md and docs/internal/diagnostics-reporting.md.
• docs/architecture/structured-llm.md: split across docs/internal/llm-runtime.md and docs/integrations/openai-compatible-llm.md.
• docs/architecture/validators.md: move and rewrite as docs/internal/validators.md.
• docs/architecture/prompts.md: move and rewrite as docs/internal/prompts.md; remove deferred and unimplemented prompt override material.
• docs/architecture/output-schemas.md: move and rewrite as docs/internal/output-schemas.md; remove deferred or unimplemented schema material such as seriatim-intermediate.
• docs/documentation/policy.md: merge/delete in favor of docs/policy/documentation.md. It duplicates policy material in a noncanonical location.
• docs/integration/subprocess-operations.md: move and rewrite as docs/integrations/subprocess.md.
• docs/release-checklist.md: merge current-behavior checks into docs/policy/development.md or move to a clearer policy/internal location; remove pre-release or deferred-feature guardrail language from non-roadmap docs.
• docs/roadmap/audit.md: currently deleted in the worktree. Treat this as unrelated state unless a later task explicitly restores or updates it.
• docs/roadmap/implementation.md: currently deleted in the worktree. Treat this as unrelated state unless a later task explicitly restores or updates it.
• examples/: create new. No examples directory is currently present, but policy expects copyable examples when practical.

Policy Compliance Assessment

Required or expected canonical documents are missing:

• docs/cli.md
• docs/config.md
• docs/operations.md
• docs/internal/
• docs/policy/development.md
• examples/

Recommended documents that should be added:

• docs/troubleshooting.md
• docs/integrations/openai-compatible-llm.md
• docs/integrations/transcript-glossary-files.md

Documents in the wrong canonical home:

• docs/configuration.md should become docs/config.md.
• docs/development.md should become docs/policy/development.md.
• docs/integration/ should become docs/integrations/.
• Implemented internal architecture content under docs/architecture/ should move to docs/internal/.
• docs/documentation/policy.md should merge/delete in favor of docs/policy/documentation.md.

Content that should not remain outside docs/roadmap/:

• Deferred or unimplemented output schema content in docs/architecture/output-schemas.md.
• Deferred or unimplemented prompt override, generated transcript description, and report prompt ledger content in docs/architecture/prompts.md.
• Pre-release or future-feature guardrail language in docs/release-checklist.md, unless moved to roadmap or rewritten as current contributor workflow.

Examples and links:

• examples/ is missing.
• README links to nonexistent documentation paths.
• Links to docs/configuration.md, docs/development.md, and docs/integration/ should be updated after canonical moves.
• A repository-wide link/path check should be part of final validation.

Target Documentation Set

README.md

• Audience: users and operators.
• Purpose: concise project orientation and shortest useful workflow.
• Canonical scope: what Audita does, install/build basics, minimal command shape, and links to canonical docs.
• Recommended outline: overview, quickstart, minimal configuration pointer, common command pointer, documentation map, development pointer.
• Sources to inspect: cmd/audita/main.go, internal/cli/run.go, internal/cli/process_flags.go, README tests or CLI integration tests.
• Acceptance criteria: no long CLI or config reference; no stale links; all linked docs exist.

docs/cli.md

• Audience: users and operators.
• Purpose: canonical CLI reference.
• Canonical scope: commands, flags, common workflows, output destinations, stdout/stderr behavior, and exit behavior.
• Recommended outline: command overview, process, config validate, config print-effective, config path selection, process outputs, examples, exit behavior.
• Sources to inspect: internal/cli/run.go, internal/cli/process_flags.go, cmd/audita, CLI tests.
• Acceptance criteria: every implemented command and flag is documented; examples match parser behavior; config details link to docs/config.md.

docs/config.md

• Audience: administrators, operators, and advanced users.
• Purpose: canonical configuration reference.
• Canonical scope: config path resolution, precedence, YAML schema, environment overrides, CLI override relationship, secrets, validation.
• Recommended outline: loading model, precedence, file schema, environment variables, CLI relationship, secrets, examples, validation.
• Sources to inspect: internal/core/config/*, config tests, CLI config commands.
• Acceptance criteria: replaces docs/configuration.md; documents implemented defaults and validation only; examples validate.

docs/operations.md

• Audience: operators.
• Purpose: operational behavior and recovery/debugging reference.
• Canonical scope: run directories, diagnostics artifacts, reports, correction ledger, retention, output writes, failure inspection.
• Recommended outline: process run lifecycle, output files, diagnostics directory, reports, retention, operational failure modes, recovery steps.
• Sources to inspect: internal/core/diagnostics, internal/framework/processreport, internal/cli, reporting tests.
• Acceptance criteria: no resume, checkpoint, or remote storage claims; operational artifacts match implemented filenames and report behavior.

docs/troubleshooting.md

• Audience: users and operators.
• Purpose: concise guide for recurring implemented failures.
• Canonical scope: symptoms, likely causes, inspection steps, and safe fixes.
• Recommended outline: config validation errors, transcript/glossary schema errors, LLM request errors, output/report write failures, diagnostics lookup.
• Sources to inspect: CLI tests, config tests, schema tests, LLM tests, reporting tests.
• Acceptance criteria: every entry maps to implemented behavior; no speculative remediation.

docs/policy/documentation.md

• Audience: maintainers and coding agents.
• Purpose: canonical documentation policy.
• Canonical scope: documentation layout, audience boundaries, roadmap rules, maintenance rules.
• Recommended outline: keep current structure unless policy itself needs small alignment.
• Sources to inspect: documentation policy and final documentation tree.
• Acceptance criteria: remains the only canonical documentation policy.

docs/policy/architecture.md

• Audience: developers and coding agents.
• Purpose: canonical architecture policy.
• Canonical scope: development principles, boundaries, invariants, dependency policy, testing expectations.
• Recommended outline: keep current policy; update links after docs migration only if necessary.
• Sources to inspect: package layout and policy docs.
• Acceptance criteria: no stale links; no duplicated CLI/config reference.

docs/policy/development.md

• Audience: developers and coding agents.
• Purpose: contributor workflow and change expectations.
• Canonical scope: repo layout, setup, tests, conventions, adding config/CLI/module/validator/docs/examples.
• Recommended outline: setup, repository layout, running tests, change workflow, adding features, documentation expectations, release checks.
• Sources to inspect: docs/development.md, tests, go.mod, package layout.
• Acceptance criteria: replaces docs/development.md; no future-feature roadmap content; includes practical validation commands.

docs/internal/overview.md

• Audience: developers and coding agents.
• Purpose: implemented internal architecture overview.
• Canonical scope: core/framework/module/validator/adapter layout at a high level.
• Recommended outline: package map, main execution path, boundary summary, where to add new code.
• Sources to inspect: internal/core, internal/framework, internal/modules, internal/validators, internal/cli.
• Acceptance criteria: concise internal entry point; links to detailed internal docs.

docs/internal/pipeline.md

• Audience: developers and coding agents.
• Purpose: implemented process pipeline.
• Canonical scope: transcript loading, normalization, chunking, module proposal generation, validation, deterministic application, output/report handoff.
• Recommended outline: inputs, pipeline phases, runner outputs, failure behavior, tests.
• Sources to inspect: internal/framework/runner, internal/core/normalization, internal/core/chunking, CLI process tests.
• Acceptance criteria: no unimplemented workflow engine or resume claims.

docs/internal/modules.md

• Audience: developers and coding agents.
• Purpose: module authoring and maintenance reference.
• Canonical scope: current module packages, module contracts, proposal behavior, prompt assets.
• Recommended outline: module contract, implemented modules, prompt ownership, proposal output, tests.
• Sources to inspect: internal/modules/*, internal/framework/contracts, internal/framework/proposal_generation.
• Acceptance criteria: keeps module packages separate; no plugin architecture claims.

docs/internal/validators.md

• Audience: developers and coding agents.
• Purpose: validator architecture reference.
• Canonical scope: validator registry, chains, deterministic and LLM-backed validators, decision handling.
• Recommended outline: validator contract, chain registration, classifications, batching, failure behavior, tests.
• Sources to inspect: internal/validators, internal/framework/validators.
• Acceptance criteria: documents composable validators without inventing new validator APIs.

docs/internal/llm-runtime.md

• Audience: developers and coding agents.
• Purpose: internal LLM runtime and scheduler reference.
• Canonical scope: StructuredLLMClient, OpenAI-compatible adapter boundary, retries, redaction, scheduler permits, structured response handling.
• Recommended outline: client interface, request/response handling, retries/timeouts, concurrency, diagnostics, tests.
• Sources to inspect: internal/framework/llm, internal/framework/responseschema, internal/framework/structuredoutput.
• Acceptance criteria: documents only implemented OpenAI-compatible HTTP behavior.

docs/internal/diagnostics-reporting.md

• Audience: developers and coding agents.
• Purpose: diagnostics, report, and correction ledger implementation reference.
• Canonical scope: artifact names, metadata, process report mapping, correction ledger, retention interaction.
• Recommended outline: diagnostics ownership, artifact metadata, process report builder, ledger mapping, tests.
• Sources to inspect: internal/core/diagnostics, internal/core/reporting, internal/framework/processreport, CLI report tests.
• Acceptance criteria: filenames and report fields match code; no planned artifact claims.

docs/internal/prompts.md

• Audience: developers and coding agents.
• Purpose: implemented prompt registry and prompt asset reference.
• Canonical scope: embedded prompt assets, prompt metadata, rendering inputs, module prompt ownership.
• Recommended outline: registry, assets, metadata, module usage, tests.
• Sources to inspect: internal/prompts, internal/framework/promptcontext, module prompt tests.
• Acceptance criteria: removes unimplemented filesystem overrides and deferred prompt ledger content.

docs/internal/output-schemas.md

• Audience: developers and coding agents.
• Purpose: implemented output schema registry reference.
• Canonical scope: supported output schemas, config validation, output emission.
• Recommended outline: registry, bare-segments, audita-v1, validation, tests.
• Sources to inspect: internal/core/outputschema, internal/core/config, schema/output tests.
• Acceptance criteria: documents only implemented schemas.

docs/integrations/subprocess.md

• Audience: operators and external-process integrators.
• Purpose: subprocess invocation contract.
• Canonical scope: invoking audita process, stdin/stdout/stderr expectations where implemented, files, reports, exit codes.
• Recommended outline: invocation model, outputs, diagnostics, errors, parent-process guidance.
• Sources to inspect: internal/cli, subprocess-oriented docs, CLI integration tests.
• Acceptance criteria: no non-existent streaming API or server mode.

docs/integrations/openai-compatible-llm.md

• Audience: developers and operators integrating an LLM endpoint.
• Purpose: OpenAI-compatible LLM contract.
• Canonical scope: chat completions request behavior, JSON schema response format, retries, timeouts, redaction, configured endpoints.
• Recommended outline: endpoint expectations, authentication, response format, retry/timeout behavior, diagnostics and redaction.
• Sources to inspect: internal/framework/llm, config LLM settings, LLM tests.
• Acceptance criteria: no provider SDK or non-OpenAI-compatible API claims.

docs/integrations/transcript-glossary-files.md

• Audience: users, operators, and external systems producing input files.
• Purpose: accepted transcript and glossary file contracts.
• Canonical scope: implemented JSON/YAML shapes and validation behavior.
• Recommended outline: transcript shape, glossary shape, validation errors, example files.
• Sources to inspect: internal/core/schema, schema tests, CLI input tests.
• Acceptance criteria: does not invent a formal versioned schema beyond implemented fields.

examples/

• Audience: users and operators.
• Purpose: copyable, maintained examples.
• Canonical scope: minimal and fuller config, tiny transcript, tiny glossary.
• Recommended files: minimal-config.yml, production-config.yml, tiny-transcript.json, tiny-glossary.yaml.
• Sources to inspect: config defaults/tests, schema tests, CLI tests.
• Acceptance criteria: no secrets; config examples validate; examples are linked from README, CLI, and config docs.

docs/roadmap/documentation.md

• Audience: maintainers and coding agents.
• Purpose: staged documentation migration plan.
• Canonical scope: future documentation work only.
• Recommended outline: this file.
• Sources to inspect: repository docs, code, tests, documentation policy, architecture policy.
• Acceptance criteria: remains action-oriented and does not rewrite current documentation prematurely.

File-by-File Rewrite Guidance

README

Cover project purpose, shortest useful command, build/test basics, and links to canonical docs. Avoid full CLI flag lists, full config schema, diagnostics reference, module internals, and architectural history. Link to docs/cli.md, docs/config.md, docs/operations.md, docs/troubleshooting.md, and policy docs after those files exist. Do not carry forward stale links to nonexistent docs/diagnostics.md, docs/structured-llm.md, or docs/subprocess-operations.md.

docs/config.md

Rewrite from docs/configuration.md. Cover path resolution, precedence, YAML schema, env overrides, CLI override relationship, validation, and secrets. Link to docs/cli.md for command syntax and to examples for copyable files. Inspect internal/core/config/* and config tests. Avoid duplicating every CLI flag except where needed to explain precedence.

docs/cli.md

Build from internal/cli/run.go, internal/cli/process_flags.go, and CLI tests. Cover process, config validate, and config print-effective. Include implemented output destinations and subprocess-friendly behavior. Link to docs/config.md for configuration details and docs/operations.md for diagnostics and reports. Avoid documenting unsupported command aliases or future commands.

docs/operations.md

Merge operational material from diagnostics and subprocess docs. Cover run directories, diagnostics artifacts, reports, correction ledger, retention, output/report writes, and safe failure inspection. Inspect internal/core/diagnostics, internal/framework/processreport, and CLI tests. State that resume, checkpoint, and remote storage are not implemented only if needed to avoid user confusion.

docs/troubleshooting.md

Create concise symptom/cause/inspect/fix entries for implemented failures. Inspect config validation tests, schema tests, LLM adapter tests, reporting tests, and CLI integration tests. Avoid broad operational advice that is not supported by the repository.

docs/policy/development.md

Move and rewrite from docs/development.md. Cover setup, package layout, tests, conventions, and how to add config fields, CLI flags, modules, validators, docs, and examples. Merge any still-useful current-behavior release checks from docs/release-checklist.md. Avoid roadmap, pre-1.0 history, and deferred-feature guardrail language.

docs/internal/*

Move implemented architecture details out of docs/architecture/*. Keep these docs concise and developer-facing. Remove deferred or unimplemented sections such as seriatim-intermediate, prompt overrides, generated transcript descriptions, report-level prompt ledgers, plugin systems, workflow engines, resume, and remote storage.

docs/integrations/subprocess.md

Move from docs/integration/subprocess-operations.md. Keep stdout/stderr, file outputs, exit behavior, diagnostics/report handling, and parent-process guidance that matches current CLI behavior. Do not document non-existent streaming APIs.

docs/integrations/openai-compatible-llm.md

Derive from implemented internal/framework/llm behavior and the current structured LLM architecture doc. Cover OpenAI-compatible chat completions, response_format.type=json_schema, retries, timeouts, and redaction. Do not claim support for provider SDKs or non-OpenAI-compatible APIs.

docs/integrations/transcript-glossary-files.md

Create from implemented schema loading and validation. Cover the file shapes accepted by Audita and link to examples. Do not invent a formal external schema version beyond what the code validates.

docs/documentation/policy.md

Delete after verifying any unique useful policy content is already in docs/policy/documentation.md. Do not keep two documentation policy homes.

docs/release-checklist.md

Either merge current-behavior contributor checks into docs/policy/development.md or move a concise checklist to a clearer policy/internal location. Remove future-feature or deferred-work guardrails from non-roadmap documentation.

Examples Plan

Create maintained, non-secret examples only for implemented behavior.

examples/minimal-config.yml

• Purpose: smallest useful config with version: 1, output schema, and api_key_env.
• Expected validity check: go run ./cmd/audita config validate --config examples/minimal-config.yml.
• Link from: README.md, docs/config.md, docs/cli.md.

examples/production-config.yml

• Purpose: fuller config showing modules, LLMs, concurrency, chunking, normalization, thresholds, context, and diagnostics.
• Expected validity check: go run ./cmd/audita config validate --config examples/production-config.yml.
• Link from: docs/config.md.

examples/tiny-transcript.json

• Purpose: small copyable transcript input for CLI examples and schema documentation.
• Expected validity check: schema tests or a no-live-LLM CLI parser path if practical.
• Link from: README.md, docs/cli.md, docs/integrations/transcript-glossary-files.md.

examples/tiny-glossary.yaml

• Purpose: small copyable glossary input for CLI examples.
• Expected validity check: schema tests or a no-live-LLM CLI parser path if practical.
• Link from: README.md, docs/cli.md, docs/integrations/transcript-glossary-files.md.

Do not add examples for resume, remote storage, prompt overrides, plugin systems, UI/server mode, unsupported output schemas, or other unimplemented behavior.

Internal Documentation Plan

Pipeline

• Path: docs/internal/pipeline.md
• Purpose: document the implemented transcript processing pipeline.
• Inputs and outputs: normalized transcript, sections, configured module specs, proposal results, validation results, runner output.
• Boundaries: runner orchestrates; modules propose; validators filter; accepted proposals are applied deterministically.
• Config fields used: modules, output schema, chunking, normalization, thresholds, concurrency, context, diagnostics.
• Adapters used: LLM client through framework contracts; filesystem/reporting through CLI and diagnostics boundaries.
• Failure behavior: module and validator warnings, rejected proposals, run/report error status.
• Tests to inspect: runner tests, proposal generation tests, CLI parity and release fixture tests.
• Architectural invariants: keep nondeterministic LLM effects isolated from deterministic transcript state handling.

Modules

• Path: docs/internal/modules.md
• Purpose: document implemented correction modules and their contracts.
• Inputs and outputs: contracts.ProposalRequest, module proposals, warnings, replacement policies.
• Boundaries: one package per module; prompt assets remain module-specific; shared framework plumbing stays outside module packages.
• Config fields used: configured module keys, LLM settings, chunking/context where applicable.
• Adapters used: LLM client only through contracts and proposal generation framework.
• Failure behavior: proposal warnings and malformed LLM output handling as implemented.
• Tests to inspect: internal/modules/... and proposal generation tests.
• Architectural invariants: keep module scope narrow and avoid hidden global state.

Validators

• Path: docs/internal/validators.md
• Purpose: document validator composition and decision handling.
• Inputs and outputs: candidate proposals, validator decisions, rejection reasons, warnings.
• Boundaries: validator registry and chains live in internal/validators; runtime mechanics live in internal/framework/validators.
• Config fields used: thresholds, validation LLM settings, validation concurrency, validation prompt limits.
• Adapters used: LLM-backed validators use the LLM contract rather than direct transport.
• Failure behavior: rejected proposals, warning behavior, malformed output policy.
• Tests to inspect: validator registry, chain, batching, malformed output, protected terms, and LLM validator tests.
• Architectural invariants: validators remain modular and composable.

LLM Runtime

• Path: docs/internal/llm-runtime.md
• Purpose: document structured LLM calls and bounded scheduling.
• Inputs and outputs: structured prompt requests, response schemas, parsed responses, scheduler permit results, diagnostics metadata.
• Boundaries: transport stays behind StructuredLLMClient; scheduler manages permits; response schema registry owns schema metadata.
• Config fields used: model, base URL, API key, timeout, retries, total/proposal/validation concurrency, validation max prompt tokens.
• Adapters used: OpenAI-compatible HTTP adapter.
• Failure behavior: retries, timeout/context handling, malformed structured output handling, redacted errors.
• Tests to inspect: LLM client, scheduler, redaction, response schema, structured output tests.
• Architectural invariants: keep concurrency bounded and explicit; do not leak secrets in diagnostics.

Diagnostics and Reporting

• Path: docs/internal/diagnostics-reporting.md
• Purpose: document diagnostics artifacts, process reports, and correction ledger generation.
• Inputs and outputs: run directory artifacts, diagnostics metadata, process report JSON, correction ledger entries.
• Boundaries: diagnostics owns artifact names and metadata; processreport maps runner output to reporting structures; CLI chooses output destinations.
• Config fields used: work dir, work-dir retention, transcript description.
• Adapters used: filesystem through diagnostics/CLI boundaries.
• Failure behavior: report status/error mapping and artifact write errors as implemented.
• Tests to inspect: diagnostics tests, processreport tests, CLI report fixture tests.
• Architectural invariants: preserve diagnostics filenames and report JSON shape unless intentionally changed and documented.

Prompts

• Path: docs/internal/prompts.md
• Purpose: document implemented prompt registry, embedded assets, and metadata.
• Inputs and outputs: prompt identifiers, prompt asset content, rendered prompt payloads, diagnostic metadata.
• Boundaries: prompt assets remain owned by module/framework areas that use them; no filesystem override mechanism is implemented.
• Config fields used: transcript description/context where applicable.
• Adapters used: none directly; prompts are consumed by LLM-backed framework code.
• Failure behavior: missing or malformed embedded prompt assets should surface through tests or runtime errors as implemented.
• Tests to inspect: prompt registry and module prompt tests.
• Architectural invariants: keep prompt metadata consistent with diagnostics.

Output Schemas

• Path: docs/internal/output-schemas.md
• Purpose: document implemented output schema registry and report/output relationship.
• Inputs and outputs: configured output schema key, validated schema support, emitted transcript output.
• Boundaries: output schema registry lives in internal/core/outputschema; config validation consumes registry support.
• Config fields used: output schema.
• Adapters used: none directly.
• Failure behavior: unsupported schema keys fail validation.
• Tests to inspect: output schema and config validation tests.
• Architectural invariants: do not document unsupported schemas as current behavior.

Integration Documentation Plan

docs/integrations/subprocess.md

• External system or contract: parent process invoking the audita CLI.
• Current usage in Audita: audita process writes output/report files and emits subprocess-friendly diagnostics and errors.
• Version or compatibility notes: document only the current CLI behavior and implemented exit behavior.
• What to document: invocation model, command examples, output files, report JSON path, stderr/stdout expectations, diagnostics, exit codes.
• What not to document: streaming protocols, server mode, remote job control, resume APIs.

docs/integrations/openai-compatible-llm.md

• External system or contract: OpenAI-compatible chat completions endpoint using JSON schema response format.
• Current usage in Audita: configured primary and validation LLM clients issue structured chat completion requests with retries/timeouts and redaction.
• Version or compatibility notes: document compatibility based on request behavior in internal/framework/llm, not provider marketing claims.
• What to document: endpoint configuration, authentication, request/response expectations, response_format.type=json_schema, retries, timeouts, redaction.
• What not to document: unsupported provider SDKs, non-OpenAI-compatible APIs, unimplemented model-routing features.

docs/integrations/transcript-glossary-files.md

• External system or contract: transcript JSON and glossary YAML files accepted as inputs.
• Current usage in Audita: CLI loads transcript and glossary files before processing and validates their shape through core schema code.
• Version or compatibility notes: document implemented fields and validation behavior only.
• What to document: accepted file shapes, required/optional fields, common validation errors, tiny examples.
• What not to document: a formal versioned external schema that the code does not enforce.

Recommended Implementation Sequence

Stage 1: Roadmap Creation

• Goal: create this documentation roadmap.
• Files to create/update/delete/move: create docs/roadmap/documentation.md only.
• Repository areas to inspect: documentation policy, architecture policy, existing docs, CLI/config/package/test layout.
• Acceptance criteria: roadmap is action-oriented, staged, and limited to future documentation work.
• Suggested validation commands: git diff --check -- docs/roadmap/documentation.md.
• One prompt: yes.

Stage 2: Canonical Layout and README Links

• Goal: establish canonical paths and remove obvious stale links without rewriting all content.
• Files to create/update/delete/move: create target directories, move/rewrite shells for docs/config.md, docs/policy/development.md, docs/integrations/subprocess.md, and update README links; remove old duplicates only after content is preserved.
• Repository areas to inspect: docs policy, README, moved docs.
• Acceptance criteria: canonical paths exist; README does not link to nonexistent docs; old paths are either redirected by content moves or removed.
• Suggested validation commands: rg "docs/(diagnostics|structured-llm|subprocess-operations)\\.md" README.md docs; rg "docs/configuration\\.md|docs/development\\.md|docs/integration/" README.md docs.
• One prompt: yes.

Stage 3: README and CLI Reference

• Goal: make README concise and create complete docs/cli.md.
• Files to create/update/delete/move: README.md, docs/cli.md.
• Repository areas to inspect: cmd/audita/main.go, internal/cli/run.go, internal/cli/process_flags.go, CLI tests.
• Acceptance criteria: README is orientation only; all implemented commands and flags are covered in docs/cli.md; examples match parser behavior.
• Suggested validation commands: go test ./internal/cli ./cmd/audita; stale-link grep checks.
• One prompt: yes.

Stage 4: Config Reference and Examples

• Goal: rewrite docs/config.md and add maintained copyable examples.
• Files to create/update/delete/move: docs/config.md, examples/minimal-config.yml, examples/production-config.yml, examples/tiny-transcript.json, examples/tiny-glossary.yaml; remove docs/configuration.md after migration.
• Repository areas to inspect: internal/core/config/*, config tests, schema tests.
• Acceptance criteria: config reference matches implemented defaults, precedence, env vars, validation, and secrets; examples contain no secrets and validate where practical.
• Suggested validation commands: go test ./internal/core/config; go run ./cmd/audita config validate --config examples/minimal-config.yml; go run ./cmd/audita config validate --config examples/production-config.yml.
• One prompt: yes.

Stage 5: Operations and Troubleshooting

• Goal: create operational and troubleshooting references.
• Files to create/update/delete/move: docs/operations.md, docs/troubleshooting.md.
• Repository areas to inspect: internal/core/diagnostics, internal/framework/processreport, internal/core/reporting, CLI failure/report tests.
• Acceptance criteria: implemented artifacts, retention, reports, correction ledger, and failure inspection are documented; no resume or remote-storage claims.
• Suggested validation commands: go test ./internal/core/diagnostics ./internal/framework/processreport ./internal/cli.
• One prompt: yes.

Stage 6: Internal Architecture Docs Migration

• Goal: move implemented architecture details into docs/internal/ and remove roadmap content from non-roadmap docs.
• Files to create/update/delete/move: docs/internal/overview.md, docs/internal/pipeline.md, docs/internal/modules.md, docs/internal/validators.md, docs/internal/llm-runtime.md, docs/internal/diagnostics-reporting.md, docs/internal/prompts.md, docs/internal/output-schemas.md; migrate/delete relevant docs/architecture/*.
• Repository areas to inspect: internal/core, internal/framework, internal/modules, internal/validators, internal/prompts.
• Acceptance criteria: internal docs document implemented behavior only; deferred or unimplemented content appears only under docs/roadmap/.
• Suggested validation commands: go test ./internal/framework/llm ./internal/framework/runner; go test ./internal/validators/...; go test ./internal/modules/...; rg "deferred|not implemented|future|planned|experimental|aspirational" docs --glob '!docs/roadmap/**'.
• One prompt: split if needed into pipeline/modules/validators and LLM/diagnostics/prompts/output schemas.

Stage 7: Integration Docs

• Goal: create external contract docs for implemented integrations.
• Files to create/update/delete/move: docs/integrations/subprocess.md, docs/integrations/openai-compatible-llm.md, docs/integrations/transcript-glossary-files.md; remove docs/integration/ after migration.
• Repository areas to inspect: CLI behavior, internal/framework/llm, internal/core/schema, integration-related tests.
• Acceptance criteria: integration docs describe actual external contracts and do not claim unsupported APIs.
• Suggested validation commands: go test ./internal/cli ./cmd/audita; go test ./internal/framework/llm; schema package tests.
• One prompt: yes.

Stage 8: Development Policy and Duplicate Cleanup

• Goal: finish contributor workflow docs and remove duplicate policy locations.
• Files to create/update/delete/move: docs/policy/development.md, docs/documentation/policy.md, docs/release-checklist.md, any remaining old architecture/config/development paths.
• Repository areas to inspect: policy docs, development docs, test layout, final documentation tree.
• Acceptance criteria: one canonical documentation policy, one canonical development workflow, no duplicate or stale canonical-home references.
• Suggested validation commands: find docs -type f | sort; grep checks for old paths and duplicate policy paths.
• One prompt: yes.

Stage 9: Final Documentation Validation

• Goal: repository-wide documentation review after migration.
• Files to create/update/delete/move: all documentation and examples touched by prior stages only as needed for fixes.
• Repository areas to inspect: final docs tree, README, examples, code-backed docs.
• Acceptance criteria: canonical docs exist, stale docs removed, examples valid, no unimplemented claims outside roadmap, Go tests pass.
• Suggested validation commands: go test ./...; all grep/link checks in this roadmap; example validation commands.
• One prompt: yes.

Validation Plan

No markdown or documentation linter configuration was found. Use repository behavior tests, whitespace checks, grep checks, and manual review.

Automated checks:

• git diff --check
• go test ./internal/core/config
• go test ./internal/cli ./cmd/audita
• go test ./internal/core/diagnostics ./internal/framework/processreport
• go test ./internal/framework/llm ./internal/framework/runner
• go test ./...

Example checks after examples exist:

• go run ./cmd/audita config validate --config examples/minimal-config.yml
• go run ./cmd/audita config validate --config examples/production-config.yml

Recommended grep and path checks:

• rg "docs/(diagnostics|structured-llm|subprocess-operations)\\.md" README.md docs
• rg "docs/configuration\\.md|docs/development\\.md|docs/integration/" README.md docs
• rg "deferred|not implemented|future|planned|experimental|aspirational" docs --glob '!docs/roadmap/**'
• find docs -type f | sort
• find examples -type f | sort

Manual review:

• Confirm README is concise and links to canonical docs.
• Confirm CLI and config docs do not duplicate each other.
• Confirm internal docs are developer-facing and not user manuals.
• Confirm operations and troubleshooting docs describe current behavior only.
• Confirm future work appears only under docs/roadmap/.
• Confirm examples contain no secrets or private transcript data.

Open Questions

No questions block the roadmap. Use these defaults unless a later implementation prompt says otherwise:

• Use the canonical paths from docs/policy/documentation.md, even when that requires moving existing docs.
• Treat docs/configuration.md, docs/development.md, docs/integration/, and docs/architecture/* as migration sources, not final homes.
• Do not restore deleted roadmap files unless separately requested.
• Prefer concise canonical docs over preserving historical wording from stale files.