176 lines
8.8 KiB
Markdown
176 lines
8.8 KiB
Markdown
# Adopt Audita v3 and independent diagnostic destinations
|
|
|
|
## Purpose
|
|
|
|
Adopt Audita v3.0.0 for transcript polishing and use its independent output
|
|
destinations to implement the Audita portion of the
|
|
[session workspace roadmap](workspace.md). Operators should find the completed
|
|
transcript, ordinary reports, and optional debug evidence in their respective
|
|
Narratio locations.
|
|
|
|
This document defines the Audita adoption scope and target. The workspace
|
|
roadmap owns shared layout, latest-attempt views, and retention behavior. Its
|
|
referenced ADRs remain Proposed. Implementation sequencing belongs in a
|
|
subsequent implementation plan.
|
|
|
|
## Reviewed Upstream Release
|
|
|
|
The reviewed Audita v3.0.0 tag identifies commit
|
|
`3b4933256eff84327b812e7ae12babf743bc04a6`. Its
|
|
[release notes](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/releases/v3.0.0.md),
|
|
[CLI reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/cli.md),
|
|
[configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/config.md),
|
|
and [operations guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/operations.md)
|
|
own the downstream contracts.
|
|
|
|
Audita now honors an explicit `--report-dir` alongside file transcript output.
|
|
Its existing `--work-dir` selects the parent of retained debug captures, with
|
|
capture enabled separately through configuration or `--debug`. These controls
|
|
satisfy Narratio's requested destination separation. Further upstream changes
|
|
are unnecessary for this scope.
|
|
|
|
## Current Baseline
|
|
|
|
Narratio's [Audita integration](../integrations/audita.md) and
|
|
[polish stage](../internal/stage-polish.md) describe the implemented behavior:
|
|
|
|
- The adapter invokes `process` with a transcript, glossary, and staged transcript
|
|
destination. It supports independent downstream configuration, overlay,
|
|
profile, module, description, and output-schema selectors.
|
|
- The adapter supplies no reporting, debug, or work-directory flags. Audita
|
|
controls debug capture and placement through its own configuration.
|
|
- Ordinary reports are discovered beside the staged transcript. The polish
|
|
stage validates returned report paths against those adjacent filenames.
|
|
- Only the validated polished transcript becomes a canonical stage output.
|
|
Reports, captured streams, and the generated invocation record are diagnostics.
|
|
- Selected credential references use Narratio's shared exact-name forwarding and
|
|
captured-stream redaction boundary.
|
|
|
|
The existing invocation remains usable with Audita v3 after deployment-side
|
|
profile migration. Narratio changes are needed to request and consume the
|
|
new destination separation.
|
|
|
|
## Targeted End State
|
|
|
|
### Products and diagnostics
|
|
|
|
Narratio supplies separate destinations for each actual polish attempt:
|
|
|
|
| Content | Destination and control |
|
|
| --- | --- |
|
|
| Corrected transcript | Run-local staging via `--output`; validated and promoted to `transcripts/polished.json` on success. |
|
|
| Ordinary reports | `runs/<run_id>/polish/logs/` via `--report-dir`. |
|
|
| Captured stdout, stderr, and Narratio invocation record | The same run-local polish log directory. |
|
|
| Optional debug evidence | `runs/<run_id>/polish/debug/` via `--work-dir`; Audita may create its own `run-*` subdirectory beneath it. |
|
|
|
|
The workspace roadmap's `logs/polish` and `debug/polish` links expose the latest
|
|
attempt. Narratio supplies actual run destinations to Audita and records those
|
|
paths in manifest diagnostics. Shared link updates and cleanup protection are
|
|
implemented by the workspace work rather than separately inside the adapter.
|
|
|
|
### Capture selection
|
|
|
|
Add an optional `pipeline.audita.debug` boolean, defaulting to false. A true
|
|
value passes `--debug`. False or omission supplies no capture override and
|
|
preserves Audita configuration and overlay behavior; it does not disable debug
|
|
enabled downstream.
|
|
|
|
Supply `--work-dir` for each executing attempt so downstream-enabled capture
|
|
also lands in the Narratio-selected debug directory. Selecting that destination
|
|
alone does not enable capture. Ordinary production operation retains Audita's
|
|
default reporting and debug settings. Narratio adds no reporting enable/disable
|
|
flag or debug-disable flag.
|
|
|
|
Debug selection affects diagnostics for an executing stage. Changing it alone
|
|
does not invalidate a completed transcript. Operators use the existing force
|
|
workflow when fresh polish or debug evidence is needed.
|
|
|
|
### Ownership and compatibility
|
|
|
|
Use a clean adoption of Audita v3's CLI contract, without version-dependent
|
|
adapter branches or legacy profile conversion. Audita continues to own its
|
|
configuration, profiles, prompts, runtime State, and diagnostic contents.
|
|
Narratio owns supplied destinations and transcript promotion.
|
|
|
|
Keep existing selectors and shared credentials such as `OPENROUTER_API_KEY` and
|
|
`RAKESTRAWHOME_API_KEY` under their configured exact names. Audita's examples
|
|
do not require Narratio to adopt application-specific credential aliases.
|
|
Operators continue to list the credential references required by all configured
|
|
Audita backends.
|
|
|
|
Audita is a separately installed executable. Its adoption of ConfigKit v0.5.0
|
|
and PromptKit v0.12.0 does not require changing Narratio's own library
|
|
dependencies as part of this feature.
|
|
|
|
## Required Changes
|
|
|
|
### Deployment configuration migration
|
|
|
|
Document the manual migration of Audita-owned PromptKit files:
|
|
|
|
- Wrap profile definitions under keyed `profiles:` mappings, remove inner `id`
|
|
fields, and replace `base_profile` with `extends`. Preserve selected profile
|
|
IDs when appropriate.
|
|
- Review explicit zeros, omitted values, and nulls against the new generation
|
|
control semantics. Validate the final configuration root, including unused
|
|
definitions and backend references.
|
|
- Rename any backend literally named `extends` and update its references.
|
|
- Validate production configuration and each used testing overlay with Audita's
|
|
offline `config validate` command. Audita application configuration continues
|
|
to use `version: 2`.
|
|
|
|
Keep the detailed downstream format owned by the pinned Audita documentation.
|
|
Narratio does not inspect, rewrite, or automatically migrate these files.
|
|
Deployment can migrate Audita before the workspace changes land.
|
|
|
|
### Adapter and polish stage
|
|
|
|
Carry explicit report and debug destinations through the Audita request and
|
|
construct the supported flags inside the adapter. Wire the debug selector
|
|
through configuration and runner composition.
|
|
|
|
Discover the existing three report filenames in the requested report directory.
|
|
Update polish's expected-path validation to the same location. Update invocation
|
|
records and safe result metadata to describe the selected destinations and
|
|
capture request. Preserve available failure evidence and the original subprocess
|
|
error.
|
|
|
|
Keep existing transcript validation, report read bounds, timeouts, credential
|
|
forwarding, and captured-stream redaction. Reports remain optional diagnostics;
|
|
early failures or downstream-disabled reporting may produce none. Exit-zero
|
|
runs with recoverable model errors remain successful. A nonzero exit, including
|
|
a late report-write failure, never authorizes transcript promotion. Narratio
|
|
does not add report-schema parsing or report-status success gates.
|
|
|
|
### Workspace integration and lifecycle
|
|
|
|
Use the shared workspace path owner for run-local log/debug destinations and
|
|
the agreed latest-attempt behavior. Preserve previous views on skipped stages;
|
|
actual attempts refresh both views, including on failure. An attempt without
|
|
debug capture exposes an empty current debug directory.
|
|
|
|
Keep full Audita debug bundles local in this feature. Preserve existing declared
|
|
diagnostic publication and apply the workspace roadmap's retention protection
|
|
to latest link targets. This feature inherits that roadmap's clean session
|
|
cutover and unchanged treatment of older completed outputs after invalidation
|
|
or failed replacement.
|
|
|
|
### Documentation and verification
|
|
|
|
When implemented, update the configuration reference and examples, Audita
|
|
integration contract, polish internals, and operator guide. Reference Audita v3's
|
|
profile migration and explain the shared Audita/Notarius overlay development
|
|
workflow. Downstream configuration edits behind unchanged selectors still
|
|
require explicitly forcing the affected stage to replace reused outputs.
|
|
|
|
Revise the workspace roadmap's upstream-request description when this adoption
|
|
is incorporated; Audita v3.0.0 supplies the previously missing capability.
|
|
|
|
Use focused offline tests for separate transcript/report/debug destinations,
|
|
enable-only debug selection, capture enabled by downstream configuration,
|
|
available failure reports, and preservation of nonzero-exit behavior. Verify
|
|
that reports remain diagnostics and only a successful validated transcript is
|
|
promoted. Shared latest-view and cleanup tests belong to the workspace change.
|
|
Default Narratio tests use subprocess doubles and temporary filesystems and
|
|
remain independent of sibling checkouts, real credentials, and paid providers.
|