Plan the Audita adoption sprint
This commit is contained in:
@@ -4,9 +4,9 @@
|
||||
|
||||
**Status:** Adoption target and design decisions resolved; the upstream release
|
||||
gate is satisfied. Implementation remains pending. The
|
||||
[master roadmap](library-adoption.md) owns shared direction, exact dependency
|
||||
revisions, and sequencing; ConfigKit and
|
||||
PromptKit contracts are developed in [their](configkit.md) [outlines](promptkit.md).
|
||||
[master roadmap](library-adoption.md) owns shared direction and exact dependency
|
||||
revisions; the [implementation plan](implementation.md) owns sequencing. See the
|
||||
[ConfigKit](configkit.md) and [PromptKit](promptkit.md) outlines for their contracts.
|
||||
|
||||
## Baseline and Target
|
||||
|
||||
@@ -244,10 +244,8 @@ Audita processing context. Request preview and validation operate on supplied
|
||||
inputs; representative validator candidates can come from maintained fixtures
|
||||
without running proposal inference as part of request construction.
|
||||
|
||||
Establish runtime and request construction first, then wire preview and
|
||||
validation, followed by smoke commands and assembled-CLI verification. All are
|
||||
required adoption scope. Address concrete integration blockers upstream rather
|
||||
than silently omitting standard capabilities.
|
||||
All three capabilities are required adoption scope. Address concrete integration
|
||||
blockers upstream rather than silently omitting standard capabilities.
|
||||
|
||||
For standard CommandKit commands passed through by Audita, provide a concise
|
||||
link to the upstream documentation for the adopted version. Upstream owns their
|
||||
@@ -257,50 +255,23 @@ limitations of the standard capabilities. Audita documentation covers only its
|
||||
own selectors, request construction, domain inputs, and application-specific
|
||||
behavior. Apply this documentation boundary to the whole standard command suite.
|
||||
|
||||
## Work Outline
|
||||
## Integration Boundaries
|
||||
|
||||
The adoption gate above is satisfied. Follow the master sequence and selected
|
||||
released dependency set when implementing this outline.
|
||||
The native `app` and PromptKit configuration scopes are distinct. Both sides of
|
||||
native comparison use their own selected inputs. Scope validation follows native
|
||||
scope behavior; process preflight checks what execution needs. The same
|
||||
engine-loading path and
|
||||
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved)
|
||||
serve processing and all standard PromptKit commands. ReleaseKit supplies the
|
||||
application version; CommandKit owns standard flags, formats, help, completion,
|
||||
and outcomes, including native comparison status 3.
|
||||
|
||||
1. Inventory Audita commands, arguments, flags, supplied empty/false/zero values,
|
||||
streams, and exit behavior against standard declarations. Record intentional
|
||||
migrations rather than recreating the old parser around CommandKit.
|
||||
2. Establish shared loaders and scopes using the native ConfigKit and PromptKit
|
||||
integrations. Use the same engine-loading path for processing and every
|
||||
PromptKit inspection, preview, validation, and smoke command, following the
|
||||
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
|
||||
Keep configuration/resource inspection distinct from preparing
|
||||
an actual domain request. Standard scope validation need not reproduce the
|
||||
current combined settings-and-two-roles command; process setup must still
|
||||
establish what execution needs. Review generic override forwarding explicitly.
|
||||
3. Install standard inspection and configuration commands, native formats,
|
||||
help/version, and suite-consistent aliases/completion through supported APIs.
|
||||
Supply the application's version identity from the ReleaseKit v0.9.0
|
||||
integration selected in the master roadmap. Do not use a broad private CLI
|
||||
framework around CommandKit.
|
||||
4. Adapt domain process handlers to reporting/outcome boundaries, preserving
|
||||
transcript/artifact integrity, cancellation, and partial success. Apply the
|
||||
resolved visibility, completion-summary, and
|
||||
[output-failure rules](#output-failure-behavior--resolved). Establish the
|
||||
preflight package and its [output preparation](#output-resource-preparation-during-preflight--resolved)
|
||||
through the output-session component. The later glossary feature extends the
|
||||
same package with its collection-readiness checks before resource preparation.
|
||||
Standard command statuses, including comparison status
|
||||
3, should not be forced into the old Audita-only status table without a domain
|
||||
reason. Validate quiet mode against the transcript destination before creating
|
||||
outputs or starting model work, using the released reporting-mode accessor.
|
||||
Wire processing artifact capture to the released shared debug boolean; replace
|
||||
Audita's independent debug parsing with the native binding while retaining its
|
||||
application-owned capture behavior.
|
||||
5. Enable the standard preview, validation, and full smoke capabilities using the
|
||||
resolved adapter and sequencing approach above. Share Audita request helpers
|
||||
where domain additions are needed; keep generic resource inspection independent
|
||||
of those domain inputs.
|
||||
6. Update [CLI](../cli.md), [configuration](../config.md), [operations](../operations.md),
|
||||
[subprocess integration](../integrations/subprocess.md), examples, help,
|
||||
completion guidance, and migration documentation with implementation. Document
|
||||
Audita-specific behavior and link to upstream for standard command usage.
|
||||
Adopt the dependencies and exact attribution together.
|
||||
Audita supplies typed process inputs, domain request construction, preflight,
|
||||
and output-session coordination. [Glossary readiness](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
|
||||
is part of that shared phase. Standard inspection remains independent of
|
||||
processing inputs. Canonical Audita documentation owns application-specific
|
||||
behavior and the hard cutover; standard commands link to the adopted upstream
|
||||
reference. Exact selected dependencies and notices belong in attribution.
|
||||
|
||||
## Acceptance and Upstream Requests
|
||||
|
||||
|
||||
@@ -2,8 +2,9 @@
|
||||
|
||||
**Updated:** 2026-11-09
|
||||
|
||||
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
|
||||
agreed adoption policy, reviewed versions, shared sequencing, and completion.
|
||||
**Status:** Target decisions resolved; implementation pending. The
|
||||
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
|
||||
the [implementation plan](implementation.md) owns sequencing.
|
||||
|
||||
## Baseline and Target
|
||||
|
||||
@@ -92,69 +93,29 @@ native absent-main lifecycle instead of manufacturing a placeholder file or
|
||||
source record. Explicit-file errors and failures loading a selected discovered
|
||||
file remain terminal.
|
||||
|
||||
### Migration Work
|
||||
### Target Boundaries
|
||||
|
||||
1. Move imports to `go.maximumdirect.net/configkit` with the coordinated
|
||||
PromptKit cutover. Raise the toolchain as specified by the master roadmap.
|
||||
Replace `Resolution.Record` uses with the appropriate dedicated recording
|
||||
method; review affected metadata and diagnostics APIs, not only compilation.
|
||||
Relevant renamed concepts include `EntryInfo`, `Sensitive`, `LayerMain`,
|
||||
version evidence, and destination fallback. Typed `Secret` and its field tag
|
||||
retain their spelling.
|
||||
2. Adopt the native lifecycle: source composition and inheritance, typed decoding,
|
||||
explicit CLI assignments, then application resolution and validation. CLI
|
||||
assignments do not repair earlier decoding failures, alter inheritance
|
||||
relationships, or propagate parent edits through already resolved children.
|
||||
Update the current loading-order explanation and realistic integration tests.
|
||||
3. Migrate genuine source-root control blocks to `config:` where present.
|
||||
Implement the version-3 application schema and hard cutover above. Distinguish
|
||||
application schema versions from source version evidence; do not impose
|
||||
headers on every fragment merely because the API supports them.
|
||||
4. Use identified collections where records have meaningful identity. ConfigKit
|
||||
upsert replaces matching records in full; inspection follows registered
|
||||
identities through movement, while list diffs remain atomic. Preserve ordinary
|
||||
ordered/repeated pipeline stages and explicit empty-pipeline semantics:
|
||||
these express Audita domain behavior, so uniqueness/upsert is inappropriate.
|
||||
5. Integrate native source discovery and standard inspection instead of retaining
|
||||
equivalent private infrastructure. Adopt source diagnostics, explanation,
|
||||
history, normalization, and safe effective output through ckconfig. Account
|
||||
for the provenance label changing from `base` to `main`.
|
||||
6. Apply the resolved [PromptKit ownership decision](promptkit.md#backend-and-credential-ownership--resolved):
|
||||
remove Audita's separate backend mapping and LLM credential references from
|
||||
its application schema. Native PromptKit resources own those settings and
|
||||
their resolution. Coordinate the hard cutover and examples here, using the
|
||||
resolved discovery and import policy above and the
|
||||
[automatic PromptKit source contract](promptkit.md#automatic-prompt-sources--resolved).
|
||||
7. Account for the [root-default and stage-override model](glossary-stages.md#root-defaults-and-stage-overrides--resolved)
|
||||
in version-3 schema design. Implement it during the glossary feature stage
|
||||
after library adoption. Each stage resolves independently with explicit-value
|
||||
presence and source provenance, and its module and validators receive consistent
|
||||
effective settings. Apply its [selected scope and fallback rules](glossary-stages.md#configuration-scope--resolved)
|
||||
and [compound-value and clearing rules](glossary-stages.md#compound-values-and-explicit-clearing--resolved),
|
||||
together with its [CLI precedence and native-support boundary](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
|
||||
Use its [separate glossary and protection selections](glossary-stages.md#glossary-selection-and-protected-vocabulary--resolved),
|
||||
including root protection defaulting through recorded application resolution.
|
||||
Adopt its [glossary configuration ownership boundary](glossary-stages.md#glossary-configuration-ownership--resolved):
|
||||
glossary assets use native loading, composition, inheritance, collection
|
||||
identity, and typed decoding before handoff. Audita derives consumer-specific
|
||||
runtime views from that result and removes its separate glossary YAML loader.
|
||||
Use its [named collections and recursive import placement](glossary-stages.md#named-collections-and-recursive-imports--resolved),
|
||||
retaining native discovery, source context, and tier semantics.
|
||||
Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved)
|
||||
in one underlay, with higher-priority explicit main configuration.
|
||||
Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved)
|
||||
through native sequence identity registration. Apply its
|
||||
[extensible entry content contract](glossary-stages.md#entry-content-fields--resolved)
|
||||
using native typed fields and inline extension data. Honor its
|
||||
[list-input and handoff contract](glossary-stages.md#list-inputs-and-configuration-handoff--resolved):
|
||||
complete configuration resolution through ConfigKit before handoff; runtime
|
||||
consumers treat null selections as empty without restoring defaults. Follow its
|
||||
[Audita preflight boundary](glossary-stages.md#empty-collections-and-audita-preflight--resolved):
|
||||
permit empty collection configuration and check glossary-stage readiness in
|
||||
Audita after handoff, before execution.
|
||||
Apply its [optional stage identity and attribution contract](glossary-stages.md#stage-identity-and-attribution--resolved)
|
||||
and complete its required durable decision record. This application scope model
|
||||
does not change native source composition or sibling-inheritance semantics.
|
||||
The application uses the `go.maximumdirect.net/configkit` module and native
|
||||
recorded resolution, discovery, source diagnostics, and safe effective output.
|
||||
Source composition and inheritance precede typed decoding and explicit CLI
|
||||
assignment; application resolution and validation follow. CLI assignments do
|
||||
not repair earlier decoding failures, change inheritance relationships, or
|
||||
propagate parent edits through resolved children. Native source provenance uses
|
||||
`main` in place of `base`. Genuine source-root controls use `config:`.
|
||||
|
||||
PromptKit [owns backend and credential resources](promptkit.md#backend-and-credential-ownership--resolved).
|
||||
Audita's v3 schema has no separate backend or LLM credential registry. Native
|
||||
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
|
||||
remain independent of main application-file discovery.
|
||||
|
||||
The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
|
||||
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
|
||||
and [optional stage identity](glossary-stages.md#stage-identity-and-attribution--resolved).
|
||||
Glossary definitions use native composition, [default underlay sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved),
|
||||
and [collection-scoped identity](glossary-stages.md#entry-identity--resolved).
|
||||
Pipeline stages remain an ordinary ordered list, including repetitions and
|
||||
explicit empty-pipeline behavior. The application supplies domain resolution
|
||||
rules within the native lifecycle, with no second runtime defaulting pass.
|
||||
|
||||
## Documentation and Acceptance
|
||||
|
||||
|
||||
@@ -9,7 +9,8 @@ entry content fields, and optional stage IDs. Active glossary vocabulary takes
|
||||
precedence over overlapping protection. Empty collections are permitted, with
|
||||
Audita preflight rejecting empty glossary stages. Design decisions are resolved;
|
||||
implementation is pending. The
|
||||
[master roadmap](library-adoption.md) owns sequencing and release completion.
|
||||
[master roadmap](library-adoption.md) owns release completion; the
|
||||
[implementation plan](implementation.md) owns sequencing.
|
||||
|
||||
## Baseline and Target
|
||||
|
||||
@@ -401,8 +402,7 @@ sources, resolve configuration, restore defaults, or change stage inheritance.
|
||||
Keep the nonempty glossary-stage check in Audita preflight rather than ConfigKit's
|
||||
configuration-validation callbacks.
|
||||
|
||||
Implement this phase in an expressly named `internal/framework/preflight`
|
||||
package, established during CommandKit adoption and extended by this feature.
|
||||
The shared `internal/framework/preflight` package owns this phase.
|
||||
Accept fully resolved configuration and the domain inputs needed for
|
||||
readiness checks through ordinary Go functions and concrete inputs. Return
|
||||
errors identifying the affected stage and reason; CLI presentation remains with
|
||||
@@ -817,44 +817,15 @@ exceptions need a domain rationale. Link to the durable policy rather than copy
|
||||
the field inventory into multiple developer documents. This documentation work
|
||||
is part of feature acceptance, not an optional follow-up.
|
||||
|
||||
## Sequencing and Work Outline
|
||||
## Integrated Target
|
||||
|
||||
Implement after ConfigKit, PromptKit, CommandKit, and ReleaseKit adoption, and
|
||||
before final release validation and preparation. This lets the feature use the
|
||||
adopted configuration and CLI conventions and avoids adapting it twice. Keep the
|
||||
requirement visible during library design without expanding those migrations
|
||||
into feature implementation. CommandKit adoption establishes the common preflight
|
||||
package and output preparation; this feature adds glossary-specific readiness
|
||||
checks to that phase.
|
||||
|
||||
1. Apply named collection selection, default file/directory underlay imports,
|
||||
recursive placement, and the extensible entry content contract. Apply native
|
||||
CLI list conventions and the selected stage identity and attribution rules.
|
||||
Preserve the selected scope, clearing, CLI precedence, and fallback semantics
|
||||
in version 3.
|
||||
2. Adopt ConfigKit loading for glossary configuration. Register the selected
|
||||
collection identities, validate configuration contracts, and deliver final typed
|
||||
definitions and selections before transcript processing. Remove the redundant
|
||||
standalone YAML parser and local composition path.
|
||||
3. Extend `internal/framework/preflight`, established during CommandKit adoption,
|
||||
with the glossary-stage readiness check after configuration handoff. Reject any
|
||||
glossary stage whose selected collections supply no entries before output
|
||||
resource preparation or stage execution. Return readiness errors for CLI
|
||||
presentation, permit empty collection definitions, and preserve inspection
|
||||
access to them.
|
||||
4. Derive rich LLM inputs, deduplicated protection vocabulary, and glossary-stage
|
||||
exemptions from resolved configuration. Route the appropriate views through
|
||||
proposal generation and validators without mutating configuration or other
|
||||
stages. Preserve source attribution for diagnostics and inspection.
|
||||
5. Verify native composition and the domain behavior together. Account for all
|
||||
consumed configuration sources in input handling and output-collision
|
||||
protection. Make repeated stages and their selected collections understandable
|
||||
in inspection, diagnostics, and reports using optional IDs alongside position
|
||||
and module identity.
|
||||
6. Update configuration, CLI, input contracts, pipeline documentation, maintained
|
||||
examples, and hard-cutover guidance as implementation lands. Complete the ADR,
|
||||
durable policy, and future-setting classification guidance above. No runtime
|
||||
compatibility layer for the old glossary file format is required.
|
||||
The glossary feature uses the adopted ConfigKit and CommandKit conventions and
|
||||
the shared preflight/output-session boundary. It replaces the standalone glossary
|
||||
input and parsing path with typed, composed configuration. Runtime consumers
|
||||
receive derived per-stage views from that handoff; reports identify the stage
|
||||
and configuration inspection explains its effective selections and origins.
|
||||
Consumed glossary sources participate in output-collision protection. Maintained
|
||||
examples and hard-cutover guidance describe the new configuration contract.
|
||||
|
||||
## Acceptance Direction
|
||||
|
||||
|
||||
577
docs/roadmap/implementation.md
Normal file
577
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,577 @@
|
||||
# Next Major Release Implementation Plan
|
||||
|
||||
**Status:** Ready for the implementation sprint. This document assigns work;
|
||||
it does not describe implemented behavior or authorize a release.
|
||||
|
||||
Execute the numbered stages in order, one focused assignment per Luna prompt.
|
||||
Read the named roadmap sections and relevant current contracts before editing.
|
||||
Use [development guidance](../development.md) and the applicable policies,
|
||||
especially [agent discipline](../policy/agents.md), [architecture](../policy/architecture.md),
|
||||
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
|
||||
[attribution](../policy/oss.md), and [release](../policy/release.md).
|
||||
|
||||
The [master roadmap](library-adoption.md) owns the target, selected revisions,
|
||||
and release requirements. Its child roadmaps own configuration, LLM, CLI, and
|
||||
glossary behavior. Start from the current implementation: old-path ConfigKit
|
||||
v0.7.1, PromptKit v0.14.0, ReleaseKit v0.4.1, a standard-library CLI, and one
|
||||
separately parsed glossary per run. The target is a single hard cutover. Define
|
||||
final interfaces as work reaches them. Unconverted callers and tests may fail
|
||||
between stages; do not add transitional parsers, aliases, adapters between
|
||||
old/new library types, or build-only stubs. Do not make each stage pass the full
|
||||
suite or require an intermediate release or commit merely to continue. Record
|
||||
remaining dependent edits at each handoff; run focused checks when their owning
|
||||
path is available and complete validation at Stage 15.
|
||||
|
||||
Follow the selected library behavior where the roadmaps delegate ownership.
|
||||
Do not turn a useful implementation choice into a new public guarantee or test
|
||||
requirement. Keep the transcript processing and validator policies outside the
|
||||
changes expressly selected here. Use existing upstream APIs; if a concrete gap
|
||||
prevents an agreed result, record the smallest reproducer and affected contract
|
||||
before proposing an upstream request or local alternative. That is not a new
|
||||
approval gate for routine work. Use controlled providers for tests. Keep
|
||||
unrelated [deferred features](future.md) outside the sprint.
|
||||
|
||||
## Stage 1: Establish the toolchain and ReleaseKit integration
|
||||
|
||||
Read the [selected modules](library-adoption.md#baseline-and-selected-dependency-set)
|
||||
and [ReleaseKit contract](library-adoption.md#releasekit-adoption-work). Work in
|
||||
`go.mod`, `go.sum`, `scripts/release.sh`, `.woodpecker/release.yml`,
|
||||
`releasekit.json`, and the version wiring in `internal/cli`.
|
||||
|
||||
1. Set the source minimum to Go 1.27.0. Use Go 1.27.3 for the validated release
|
||||
toolchain, matching the review. Select its published Bookworm image for
|
||||
Woodpecker; if unavailable, choose an available Go 1.27 patch and use it
|
||||
consistently in the image, runbook, validation, and runtime attribution.
|
||||
Include the C compiler and cgo prerequisites for the selected race check.
|
||||
2. Select the exact versions from the master roadmap: ConfigKit v1.1.0,
|
||||
PromptKit v0.20.0, CommandKit/ckconfig/ckprompt v0.6.0, and ReleaseKit v0.9.0,
|
||||
all under `go.maximumdirect.net`. Move the ReleaseKit runtime `buildinfo`
|
||||
import and tool registration together. Move ConfigKit/PromptKit consumers in
|
||||
Stages 2–4. Retire old requirements after their imports disappear; defer
|
||||
final `go mod tidy` until all real consumers are wired. Prepare dependencies
|
||||
with `GOWORK=off` and the selected local toolchain. Do not change Audita's
|
||||
own module major suffix independently of selecting its actual release tag.
|
||||
3. Adapt the v0.9.0 launcher and tag-delivery recipe linked by the master.
|
||||
Invoke the full `go.maximumdirect.net/releasekit/cmd/releasekit` tool path
|
||||
with host GOOS/GOARCH. Preserve tagged-source bootstrap outside the worktree,
|
||||
Woodpecker variable escaping, annotated-tag peeling, event commit verification,
|
||||
and `ci-deliver --prepared` with the verified commit. Preserve the actual
|
||||
remote, product, secret mapping, and Linux amd64/arm64 targets; add
|
||||
`delivery.forge: "gitea"`. Do not reintroduce comparison with the raw tag SHA.
|
||||
4. Select the master's native validator settings exactly. Remove generic local
|
||||
bootstrap/launcher tests covered upstream; retain Audita-specific checks for
|
||||
product, targets, destination, and version injection. Source publication is
|
||||
one `publish` after the candidate is pushed to main; `check` is diagnostic.
|
||||
Keep recovery native and delivery asynchronous. No actual publication here.
|
||||
|
||||
Handoff: selected module/tool and workflow wiring, with any not-yet-migrated Go
|
||||
callers identified. The assembled version and release checks belong to Stage 15.
|
||||
|
||||
## Stage 2: Define the v3 application schema and native loader
|
||||
|
||||
Read the [ConfigKit outline](configkit.md) and glossary
|
||||
[scope inventory](glossary-stages.md#configuration-scope--resolved). Own
|
||||
`internal/core/config` and the application-loading portion of
|
||||
`internal/cli/config_input.go`. Do not implement glossary projection or stage
|
||||
execution in this stage.
|
||||
|
||||
1. Migrate to `go.maximumdirect.net/configkit` and its recorded resolution API.
|
||||
Build one typed `LoadLayered` path returning the native result (or native
|
||||
load error), using `File` for an explicitly supplied path and optional
|
||||
`SearchConfig` with `Searches(WorkingDirectory(), UserConfigDirectory(),
|
||||
UnixSystemDirectories())` otherwise. Use application name `audita`. An
|
||||
explicit empty/invalid selection fails; a selected file's failure does not
|
||||
resume search. Enable imports on operator sources. Leave the actual main
|
||||
absent on exhaustion and use result source evidence, not guessed paths.
|
||||
2. Use typed defaults with application version 3 and the main-only version
|
||||
rule. Reject supplied obsolete, null, or invalid versions with migration
|
||||
guidance; when no header is supplied, decode against v3 defaults and schema.
|
||||
Do not require headers on fragments or construct a pretend main source.
|
||||
Supply explicit `OverlayFilesystem` rooted at the invocation directory for
|
||||
a selected overlay (see [Open Questions](#open-questions)). Do not substitute
|
||||
the overlay base for the main file's native relative-import context.
|
||||
3. Define the final shape now: global preprocessing/chunking, output,
|
||||
reporting, and diagnostic-directory settings; root defaults for eligible
|
||||
stage settings; ordered `pipeline.stages` with `module`, optional `id`,
|
||||
and stage overrides. Use the existing `thresholds.<module>` root defaults
|
||||
with a stage-local `confidence_threshold`. Keep field-level `llm`,
|
||||
`validation`, and `context` groups, and nullable selectors/list values where
|
||||
the glossary roadmap allows clearing. Use native metadata to distinguish
|
||||
absent from explicit null or empty. Keep the current default ordered module
|
||||
sequence expressed as stage records and the existing numeric domain defaults
|
||||
where the roadmap leaves them unchanged. Do not auto-select profiles or
|
||||
collections. Stage 10 completes the effective settings callback.
|
||||
4. Remove `profiles_dir`, the app-owned `backends`/LLM credential configuration,
|
||||
and `diagnostics.debug` from the new schema. Retain the diagnostic directory
|
||||
setting; capture comes from the shared CLI boolean. Keep `pipeline.stages`
|
||||
an ordinary ordered list, including repeated modules and explicit `[]`.
|
||||
Keep no v2 decoder. Configure shapes for Stage 9 glossary definitions rather
|
||||
than preserving the old standalone glossary format in the final schema.
|
||||
5. Apply explicit root overrides through ConfigKit; source composition and
|
||||
native inheritance/decoding happen first. Keep schema/configuration checks
|
||||
in the loader, command readiness in preflight, and resource loading out of
|
||||
configuration validation. Do not reject inspection for lack of a processing
|
||||
profile, credentials, or populated glossary input.
|
||||
|
||||
Evidence: native result/failure and source metadata cover discovery, exhaustion,
|
||||
selected file errors, imports, overlays, v3 defaults, and changed override order.
|
||||
Exercise final v3 examples after the glossary fields are connected.
|
||||
|
||||
## Stage 3: Build the shared PromptKit engine and account for its sources
|
||||
|
||||
Use the [PromptKit outline](promptkit.md), especially its [automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
|
||||
Own engine assembly in `internal/framework/llm/runtime.go`,
|
||||
`source_paths.go`, and embedded assets/registry under `internal/prompts`.
|
||||
|
||||
1. Build the engine on the new ConfigKit types. Retain PromptKit's default-on
|
||||
catalog. Convert all seven embedded prompts to identified list records in
|
||||
`collections.audita`, with calls using `audita/<local-id>`. Preserve text,
|
||||
templates, schema references, and resource files. Remove version selection
|
||||
and descriptive prompt version metadata, without changing response-schema
|
||||
versions. Keep the embedded schemas supplied through `WithSchemaFS`.
|
||||
2. Load embedded prompt inputs in their own filesystem underlay. Add exactly
|
||||
one higher-priority operator underlay containing native optional imports of
|
||||
`prompts.yml` and recursive `prompts/` (`*.yml` and `*.yaml`), with imports
|
||||
enabled and host root/base set to the invocation directory. Both sources
|
||||
compose as strict peers. The app's `--config`, absence of a main file, and
|
||||
overlay selection do not change the import base. Use one acquisition path
|
||||
for all engine consumers. Do not pre-read/import these files in Audita,
|
||||
manufacture filenames as IDs, or add an operator-source selector.
|
||||
3. Use native root resources, collection IDs, sibling inheritance, and whole
|
||||
same-ID replacement. Remove the generated backend main layer and the
|
||||
curated profile projection. Preserve helpful classification of bad shipped
|
||||
assets versus operator source failures using native errors/source evidence
|
||||
and the existing embedded-only diagnostic where needed. Never execute a
|
||||
diagnostic fallback engine in place of a failed requested configuration.
|
||||
4. From captured inspection, collect consumed host source paths and effective
|
||||
message `content_file` paths for collision checking. Adapt to list-index
|
||||
coordinates for root and collection resources. Follow effective origins to
|
||||
the declaring host source and its relative path; handle inherited/moved
|
||||
evidence and exclude embedded/synthetic sources from host-file collisions.
|
||||
Reuse native origin evidence and the existing path comparison machinery;
|
||||
do not rediscover the directory or reopen definitions to reconstruct origins.
|
||||
|
||||
Evidence: optional absence, both inputs, nested imports and source-relative
|
||||
messages, peer conflicts, whole replacement, untouched defaults, and edit/rerun
|
||||
capture. Exercise external config elsewhere and absent main with the same CWD.
|
||||
|
||||
## Stage 4: Adapt native requests, role clients, and artifact redaction
|
||||
|
||||
Own `internal/framework/llm`, `structuredoutput`, and request construction in
|
||||
`proposal_generation` and `validators`. Use the [runtime ownership contract](promptkit.md#backend-and-credential-ownership--resolved)
|
||||
and [stage budget inventory](glossary-stages.md#configuration-scope--resolved).
|
||||
|
||||
1. Replace profile-derived local target plumbing with role clients configured
|
||||
by explicit profile ID and effective per-operation budgets. Construct clients
|
||||
against the same captured engine; a caller may select different role clients
|
||||
per stage. Bind `RunRequest.TransientRetries`, per-call schema and repair
|
||||
settings, and the logical operation context deadline. Use `PrepareExecution`
|
||||
and `RunPrepared` on the same handle, discarding unused handles. Retain domain
|
||||
response validation, observations, and error classification, including
|
||||
recoverable exhausted operations, fatal setup failures, and parent cancellation.
|
||||
2. Remove Audita registry/endpoint equality checks, direct key injection,
|
||||
per-backend secret validation, finite-cap defaults, and local target synthesis.
|
||||
Native backend/profile fields and null semantics govern execution. Backend
|
||||
admission settings are engine configuration, not per-request overrides.
|
||||
The selected ckprompt config scope has no generic `--set` forwarding; do
|
||||
not add a CLI concurrency flag or a second limiter to supply it.
|
||||
3. Extract the small shared request helpers needed for prompt IDs, shared
|
||||
instruction variables, and domain response contracts. Keep the actual
|
||||
transcript/candidate builders owned by their processing components. Remove
|
||||
prompt version from logical requests, snapshots, and evidence. Carry native
|
||||
completed request details only where they have meaning; never relabel
|
||||
resource inspection as a completed execution target.
|
||||
4. Preserve artifact/error redaction with native configuration redaction and
|
||||
Audita's own diagnostic boundary. Replace `ConfiguredSecrets`' dependence
|
||||
on the deleted backend map: use the selected library's public credential
|
||||
source metadata, including prepared request information, to mask values from
|
||||
relevant environment references when required by Audita's artifacts. Reading
|
||||
a value solely for masking must not choose the credential or reject an
|
||||
unavailable key during inspection. Keep native prepared/inspection reports
|
||||
free of resolved keys. Exercise provider errors that echo a synthetic key;
|
||||
address an actual missing public boundary upstream before adding substantial
|
||||
credential plumbing. Do not scan or dump the entire environment.
|
||||
|
||||
Evidence: local controlled requests prove actual targets, request-specific
|
||||
budgets, null/zero behavior, credential precedence, shared admission, and
|
||||
secret-safe failure evidence. Leave stage client selection to Stage 12.
|
||||
|
||||
## Stage 5: Install CommandKit routing and native configuration/resource scopes
|
||||
|
||||
Read [CommandKit operator experience](commandkit.md#agreed-operator-experience)
|
||||
and the released v0.6.0 guide linked there. Replace the routing/parser/inspection
|
||||
parts of `internal/cli`; keep `cmd/audita` responsible for process lifetime and
|
||||
streams, not the command declarations.
|
||||
|
||||
1. Build the app with CommandKit typed declarations, native help/version and
|
||||
completion, and ReleaseKit's version accessor as application identity.
|
||||
Preserve the library outcome status, including native comparison status 3.
|
||||
Help/version do not load application or engine data. Keep a typed `process`
|
||||
declaration and wire its final handler in Stage 8. Do not preserve the old
|
||||
parser as a fallback. Keep `--config`, `--overlay`, and supported application
|
||||
settings under shared typed loaders with explicit supplied-state handling.
|
||||
2. Install the `app` scope with `ckconfig.FromConfigKit` or its supported suite
|
||||
adapter over Stage 2's native result/error. Forward standard `--set` and
|
||||
comparison-side assignments for this scope only where the loader applies
|
||||
them. Respect each side's independent selections; no global cached load
|
||||
across comparison sides. Use native effective values, failure evidence,
|
||||
path discovery, explanation, sources, comparison, and redaction.
|
||||
3. Install `ckprompt.ConfigScope(loadEngine)` and the native resource and
|
||||
requirements callbacks from `ckprompt.FromEngine`. Use shared invocation
|
||||
acquisition for a selected engine and the Stage 3 loader for every call path.
|
||||
Install the full standard inventories, namespace selection, scopes, and
|
||||
inspection features; no duplicate `config print-effective` or custom
|
||||
profile-summary command. Use the released declarations and their scoped
|
||||
aliases rather than implementing a separate routing convention.
|
||||
|
||||
Evidence: native config and resource commands use the intended scope and
|
||||
source selection, including failure evidence and no-main discovery. Check
|
||||
help/version without filesystem/provider setup. Avoid requiring process readiness
|
||||
for inspection or overriding native grammar or status behavior.
|
||||
|
||||
## Stage 6: Enable standard PromptKit request and smoke commands
|
||||
|
||||
Own the remaining `internal/cli` adapters. Use
|
||||
[the resolved command scope](commandkit.md#request-preview-validation-and-smoke-commands--resolved)
|
||||
and `WithRequestPreparation`, `WithRequestValidation`, and `WithSmokeTesting`
|
||||
from ckprompt v0.6.0. Install all capabilities with the Stage 5 declarations.
|
||||
|
||||
1. Forward the released native requests, overrides, namespaces, formats, and
|
||||
outcomes. Use the same engine acquisition as processing. For Audita-owned
|
||||
prompt IDs, supply shared instruction variables from the Stage 4 helper
|
||||
only where absent; leave explicit values and generic requests intact.
|
||||
Use native profile selection, not a guessed stage or automatic role/profile
|
||||
default. Use native prompt output definitions for generic requests. Document
|
||||
the inputs needed to preview the maintained Audita fixtures; where an adapter
|
||||
adds a domain contract, call the same request helper as processing.
|
||||
2. Validate and preview supplied fixtures without inference, including a
|
||||
validator candidate fixture. Keep preparation distinct from resource
|
||||
inspection. Install the entire upstream smoke surface, including aggregate
|
||||
behavior; smoke runs only on explicit invocation. Do not add startup probes,
|
||||
custom output shaping, or acceptance requiring a live provider.
|
||||
|
||||
Evidence: assembled CLI wiring uses shared operator replacements across
|
||||
inspection, preview, validation, and controlled smoke. Verify native output and
|
||||
status handoff without duplicating the upstream command grammar suite.
|
||||
|
||||
## Stage 7: Prepare and finalize output resources
|
||||
|
||||
Own `internal/core/diagnostics/output_session.go`, file/path helpers, and
|
||||
focused tests. Use the [output preparation](commandkit.md#output-resource-preparation-during-preflight--resolved)
|
||||
and [failure](commandkit.md#output-failure-behavior--resolved) contracts.
|
||||
|
||||
1. Separate pure destination selection/collision validation from resource
|
||||
preparation. Keep inactive report/debug destinations unprobed. Protect
|
||||
consumed app/engine files, effective message files, and transcript input
|
||||
against destructive output collisions. Allow intentional in-place final
|
||||
transcript replacement. Keep the chosen Audita artifact locations and
|
||||
destination selection rules where the roadmap does not change them.
|
||||
2. Prepare an open sibling temporary file for a regular transcript output;
|
||||
keep the final destination untouched until successful delivery. Publish by
|
||||
closing and replacing after successful writes, returning any required
|
||||
write/close/replace failure. Keep special pipe/device destinations direct
|
||||
and unopened until delivery (including `/dev/null`); stdout uses the caller's
|
||||
writer, which the session does not close. Do not add new parent-directory
|
||||
creation, special-file restrictions, or filesystem durability guarantees.
|
||||
3. Initialize enabled ordinary reports before processing, retaining per-file
|
||||
`in_progress` publication. Keep debug directory and initial artifact
|
||||
preparation optional and subsequent artifact creation on demand. On failure
|
||||
or cancellation clean unpublished temporary resources and owned handles;
|
||||
retain published files/evidence. Return optional debug problems for redacted
|
||||
warning presentation rather than marking the run failed solely for that loss.
|
||||
4. Preserve the primary failure when final reporting or cleanup also fails.
|
||||
Attempt remaining required reports and failed-status finalization as supported
|
||||
by the output contract. Do not remove an already published transcript,
|
||||
repeat model calls, or add a transaction spanning the output bundle.
|
||||
|
||||
Evidence: required preparation fails before execution, regular file contents
|
||||
survive preparation and abort, special files are deferred, and late failures
|
||||
retain already published output and primary failure details.
|
||||
|
||||
## Stage 8: Wire processing, common preflight, and reporting modes
|
||||
|
||||
Own `internal/cli/process.go` and the new `internal/framework/preflight`.
|
||||
Use the [named preflight boundary](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
|
||||
and the [CommandKit reporting decisions](commandkit.md#debug-reporting-and-artifact-capture--resolved).
|
||||
|
||||
1. Bind `process` with typed inputs, one transcript operand, `--output`, and
|
||||
explicitly supplied root overrides for retained settings. Use the shared
|
||||
`BoolFlag` named `debug` with false default; preserve its boolean for capture
|
||||
independently of `Invocation.ReportingMode()`. Do not parse raw argv or
|
||||
map quiet/verbose to the capture bit. Keep `--work-dir` a directory selection
|
||||
only. Do not re-declare `--glossary` or `--modules` when replacing the parser;
|
||||
Stage 10 supplies glossary selection inputs and pipeline order lives in v3 YAML.
|
||||
2. Resolve app settings and engine inputs and acquire transcript data using the
|
||||
owning loaders. Use the final runner/preflight interfaces, with the
|
||||
stage-specific input additions in Stages 9–12. Preflight takes resolved
|
||||
inputs and ordinary Go dependencies; no CLI, provider transport, config
|
||||
reload, or generic check framework. Check all invocation/readiness conditions
|
||||
and active collisions before output preparation. Have it coordinate the
|
||||
output session from Stage 7; the session owns filesystem resources.
|
||||
3. Before creating artifacts or starting model work, reject effective quiet plus
|
||||
stdout (including omitted/empty `--output`) with a usage explanation and a
|
||||
file or `/dev/null` remedy. Use the actual resolved mode, including ordering
|
||||
and aliases. Help/inspection do not take this processing path. Validate only
|
||||
selected processing requirements; native credential availability remains a
|
||||
request-time concern, not an eager all-backend check.
|
||||
4. Dispatch after required preparation, then finalize required outputs and
|
||||
return a native CommandKit outcome. Use the supplied raw output writer for
|
||||
transcript bytes. Emit the summary and created locations as Info/deferred
|
||||
Info only after successful required delivery; ordinary and quiet modes hide
|
||||
it. Send redacted optional debug failures as native warnings. Keep stream
|
||||
write failures under CommandKit's native outcome handling; domain model
|
||||
recoveries and work-unit errors do not become automatic command failures.
|
||||
|
||||
Evidence: actual process integration proves quiet/verbose/debug behavior,
|
||||
required failure versus optional debug loss, and stdout isolation. Reuse the
|
||||
roadmap's selected flag combinations; avoid retesting the full upstream parser.
|
||||
|
||||
## Stage 9: Compose and validate native glossary definitions
|
||||
|
||||
Own the glossary definition types and application load inputs. Read
|
||||
[glossary ownership and named collections](glossary-stages.md#glossary-configuration-ownership--resolved)
|
||||
through its default-source and entry-contract sections.
|
||||
|
||||
1. Define `glossary_collections` as a typed mapping with ordered `entries`.
|
||||
Register `SequenceIdentityMatching` for the collection mapping wildcard and
|
||||
`entries` destination, with literal `id` identity. Use typed known entry
|
||||
fields and a native inline string-keyed map for extension values. Enforce
|
||||
the selected entry fields without slug restrictions, global ID uniqueness,
|
||||
or validation of arbitrary extension contents.
|
||||
2. Add one application underlay with optional native `glossary.yml` and
|
||||
recursive `glossary/` imports mounted at `glossary_collections`. Set host
|
||||
base/root to the invocation directory, independent of discovered/explicit
|
||||
app main. Preserve peer conflicts, nested relative imports and placement,
|
||||
source attribution, and native cross-tier whole-record upsert. Do not use
|
||||
filename identity, a private walker, or infer that main `imports: []`
|
||||
cancels the application underlay. Use the separate PromptKit underlay for
|
||||
prompt resources, not this application glossary tier.
|
||||
3. Validate definition contracts with ConfigKit and allow empty definitions.
|
||||
Retain complete typed entries for inspection, including extension data.
|
||||
Capture consumed glossary source paths through the application result for
|
||||
Stage 8's collision checks. Remove the legacy glossary input/parser path
|
||||
as consumers move to the typed handoff in Stages 10–12; no parallel loader.
|
||||
|
||||
Evidence: representative native peers, layering, collection-scoped identities,
|
||||
recursion, source placement, extension values, and optional absence with both
|
||||
explicit and absent main configuration. Test integration, not native grammar again.
|
||||
|
||||
## Stage 10: Resolve stage settings and native CLI selection inputs
|
||||
|
||||
Own `internal/core/config` resolution and the matching process flag bindings.
|
||||
Use [stage scope](glossary-stages.md#configuration-scope--resolved),
|
||||
[clearing](glossary-stages.md#compound-values-and-explicit-clearing--resolved), and
|
||||
[CLI precedence](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
|
||||
|
||||
1. In `Definition.Resolve`, use `IsExplicit` and `EntryInfo` at real key/index
|
||||
paths, after root CLI assignment. Derive omitted root protection from a
|
||||
detached root glossary list with a recorded dependency. Copy the effective
|
||||
root values into each omitted eligible stage field independently, using
|
||||
`configkit.Default` and root dependencies. Preserve explicit false, zero,
|
||||
empty description, `[]`, and null according to the field contract. A partial
|
||||
group contributes only its children; reject group nulls natively.
|
||||
2. Apply validation-profile fallback only after combining root and stage values.
|
||||
Preserve explicit root validation selections, stage replacement, and stage
|
||||
null clearing. Assign the effective stage proposal profile when no validation
|
||||
selection remains; record the dependency with `RecordDerivedDefault` for
|
||||
an explicit null. Do not mistake a derived fallback for an explicit root value.
|
||||
Record at actual list-field paths, not the whole stage merely to cover a
|
||||
mutation. Copy mutable values so stages do not share their settings storage.
|
||||
3. Validate known modules, known selected collection names, effective per-field
|
||||
settings, and supplied IDs (nonempty, exact, unique; absence valid) through
|
||||
ConfigKit. Do not register the stage list as an identified collection. Do
|
||||
not make a root validation selection empty string a synonym for null. Preserve
|
||||
nullable selectors in the handoff; runtime treats a nil list as empty and
|
||||
never restores a default. Leave glossary nonempty and required processing
|
||||
profile readiness to preflight.
|
||||
4. Bind `--glossaries` and `--protected-terms` as single typed list values using
|
||||
CommandKit `ValueFlag` and `ParseCLIJSON`, accepting an array of names or
|
||||
`null`. Send one ConfigKit override per supplied root field; `[]` clears
|
||||
and omission contributes no override. Use the same native JSON semantics
|
||||
as ckconfig `--set`. Keep other existing root setting flags whose fields
|
||||
survive, with CommandKit supplied-state tracking. Remove `--glossary` and
|
||||
`--modules`; set pipeline order in YAML. Do not implement indexed/ID-targeted
|
||||
CLI edits or introduce another list-clearing grammar.
|
||||
|
||||
Evidence: native inspection shows copied root dependencies and explicit clears;
|
||||
CLI root changes affect only inheriting stage fields. Check the roadmap's
|
||||
validation-profile fallback cases and meaningful explicit-value distinctions.
|
||||
|
||||
## Stage 11: Derive stage vocabulary and adapt its consumers
|
||||
|
||||
Own the glossary-domain projection and the consumers in `internal/modules`,
|
||||
`internal/validators`, and `internal/framework/proposals`. Use the
|
||||
[derived views](glossary-stages.md#derived-runtime-representations--resolved)
|
||||
and [ordering and protection](glossary-stages.md#runtime-vocabulary-and-ordering--resolved)
|
||||
contracts.
|
||||
|
||||
1. Traverse selected collections then their resolved entries in order. Build
|
||||
rich prompt data from known fields only, retaining first occurrence per
|
||||
`(collection, id)` and all distinct entries. Do not forward extension
|
||||
fields or collapse entries by display name. Derive matching vocabulary from
|
||||
names, aliases, and plurals using existing matcher rules. Deduplicate
|
||||
spellings while retaining contributing identities for domain checks.
|
||||
2. Derive protection independently from the selected `protected_terms`. For a
|
||||
glossary-correction stage subtract active recognized spellings, even when
|
||||
another protected entry contributes that same spelling. Preserve unrelated
|
||||
aliases and plurals of non-active entries. Keep configured selections and
|
||||
entries intact; other stages get independently derived views. Preserve
|
||||
ambiguous-alias handling, protected-name repetition policy, and other
|
||||
existing validation business logic outside the selected exemption.
|
||||
3. Pass the appropriate rich and protection views to module prompts, local
|
||||
validation, and apply-time protection. Inspect downstream checks so none
|
||||
reconstructs full protection from the former combined glossary. Non-glossary
|
||||
modules use their selected context and full protection; empty protection
|
||||
does not disable other validators. Reuse narrow consumer representations;
|
||||
no generic runtime glossary merge engine.
|
||||
|
||||
Evidence: shared-spelling exemption plus unaffected spellings, ordered rich
|
||||
input with separate identities, and no mutation/leakage between stage views.
|
||||
Use controlled candidates for both permitted edits and still-protected cases.
|
||||
|
||||
## Stage 12: Execute the ordered effective stages and extend preflight
|
||||
|
||||
Own runner/contracts and the processing handoff. Connect Stages 4, 8, 10, and
|
||||
11 in `internal/framework/runner`, `contracts`, `preflight`, and `internal/cli`.
|
||||
|
||||
1. Convert the fully resolved typed list to ordered run specs carrying effective
|
||||
settings and vocabulary, module key, position, and optional ID. Preserve
|
||||
separate execution identity even for repeated modules. Create the stage's
|
||||
role clients from the shared engine and selected effective profiles/budgets;
|
||||
pass its own batching budget, threshold, context, and views to consumers.
|
||||
Do not rebuild/mutate backend settings per stage or re-resolve configuration
|
||||
during execution. Remove the old single-glossary and global role/budget wiring.
|
||||
2. Extend preflight to check every selected glossary-correction stage for at
|
||||
least one effective rich entry, including later stages. Keep empty definitions
|
||||
and inspection valid; an empty protection set is valid. Report stage position,
|
||||
module, optional ID, and selected collection names when unready. Check needed
|
||||
selected roles without synthetic requests or provider calls; a deliberately
|
||||
empty pipeline needs no processing model selection. Finish all readiness and
|
||||
collision checks before preparing outputs or dispatching work.
|
||||
3. Normalize and chunk once for the invocation. Run stages in order on the
|
||||
preceding stage's resulting transcript with fixed sections and deterministic
|
||||
proposal/apply/report order. Keep the existing fatal cancellation/join and
|
||||
recoverable local failure behavior, including normalized output when every
|
||||
model work unit fails recoverably. Preserve domain schemas, validation, and
|
||||
meaningful partial success; no rechunking or parallel stage traversal.
|
||||
|
||||
Evidence: party/spell/grammar controlled workflow, with the second stage seeing
|
||||
prior edits and independent vocabulary/role settings. Verify late empty-stage
|
||||
failure before outputs/model work and a valid no-stage normalization run.
|
||||
|
||||
## Stage 13: Carry stage identity through ordinary and debug evidence
|
||||
|
||||
Own `internal/framework/outcomes`, `processreport`, `structuredoutput` call
|
||||
context, and `internal/core/reporting`. Use the [stage attribution contract](glossary-stages.md#stage-identity-and-attribution--resolved).
|
||||
|
||||
1. Carry stage index/module and optional `stage_id` through work units, error and
|
||||
recovery records, correction ledger, LLM call evidence, and debug snapshots.
|
||||
Keep zero-based `stage_index` in machine records; show one-based position in
|
||||
human labels. Use the operator ID for labels when present, with position and
|
||||
module available, otherwise identify by position/module. Keep internal and
|
||||
artifact path identities based on safe generated stage coordinates; do not
|
||||
treat arbitrary valid user IDs as paths or require a slug format.
|
||||
2. Preserve the three ordinary files, status semantics, counts, and matrices in
|
||||
execution order. Add optional attribution fields to the existing schema rather
|
||||
than create a new reporting system. Escape labels for their output format.
|
||||
Keep errors/recoveries distinct from CommandKit reporter categories and debug
|
||||
evidence. Do not add raw prompts, provider causes, or credentials to ordinary
|
||||
reports. Ensure finalization and summary use the same run facts.
|
||||
|
||||
Evidence: named/unnamed/repeated/reordered stages can be distinguished in real
|
||||
reports and debug artifacts without changing stage order or collapsing records.
|
||||
Verify existing partial-success and unavailable-candidate evidence survives.
|
||||
|
||||
## Stage 14: Finish the cutover documentation, examples, and attribution
|
||||
|
||||
Update canonical owners as behavior lands; use this stage to reconcile them.
|
||||
Follow the [documentation policy](../policy/documentation.md) and glossary
|
||||
[durable record](glossary-stages.md#durable-decision-record).
|
||||
|
||||
1. Update `docs/config.md`, `docs/cli.md`, `docs/operations.md`, affected
|
||||
integration contracts and internal docs, `docs/development.md`, and README.
|
||||
Explain v3 application discovery, native resource sources, role/stage scope,
|
||||
preflight/output lifecycle, shared debug and quiet behavior, and the operator
|
||||
cutover in `docs/migrations/v3.md`. Link to the adopted upstream CLI reference
|
||||
for standard commands rather than duplicating their syntax, caveats, or
|
||||
provider warnings. Describe Audita-specific inputs and effects locally.
|
||||
2. Reconcile architecture policy with native resource/credential/admission and
|
||||
CLI ownership, recorded config resolution, and the preflight boundary.
|
||||
Add `docs/adr/0002-glossary-configuration-and-preflight.md` in Nygard format
|
||||
for glossary ownership, typed handoff, and output-session coordination.
|
||||
Index it; do not rewrite
|
||||
the accepted ReleaseKit ADR. Retain ordinary domain guarantees selected by
|
||||
the roadmaps, with no new compatibility or performance promises.
|
||||
3. Replace retired examples with maintained v3 projects: a minimal local run,
|
||||
a service/profile/overlay example, the embedded-prompt edit-and-rerun flow,
|
||||
a validator preview fixture, and two campaigns consuming a common glossary
|
||||
library. Run examples from the documented directory so automatic inputs and
|
||||
overlay context are accurate. Keep example values synthetic and cover their
|
||||
integration with controlled providers. Remove old backend/glossary layouts
|
||||
and obsolete parser-only tests, preserving substantive domain regressions.
|
||||
4. Align `docs/release.md` and release policy with the selected v0.9.0 workflow,
|
||||
validators and rationale, supported platform/toolchain choices, and native
|
||||
recovery. Update `docs/oss/attribution.md` for exact selected sources,
|
||||
incorporated material and toolchain dependencies; retire old catalog notices
|
||||
when no longer incorporated. Reuse applicable standard license texts, not
|
||||
upstream policy inventories. Preserve existing release tags and notes.
|
||||
|
||||
Evidence: all examples, canonical contracts, ADR, and notices describe the
|
||||
assembled target. No publication, new release note, or version tag is required
|
||||
in the real repository during this sprint.
|
||||
|
||||
## Stage 15: Verify the assembled target and hand it off
|
||||
|
||||
1. Run `go mod tidy` under the selected toolchain with `GOWORK=off`; inspect the
|
||||
selected module graph, imports, tool registrations, and attribution together.
|
||||
Confirm no old library identities, committed workspace files, or filesystem
|
||||
replacements remain. Review removal of superseded loaders, parser, registry,
|
||||
curated summary, and release plumbing. Update or remove assertions protecting
|
||||
obsolete behavior; do not compensate with a deletion quota or blanket tests.
|
||||
2. Finish any focused integration cases from the earlier stages. Use real loaders
|
||||
and controlled transports; concentrate on native integration, stage isolation,
|
||||
source safety, failure handling, and operator-visible behavior. Check link and
|
||||
example references. Reuse already completed checks on the same final tree.
|
||||
3. Use the adopted ReleaseKit `check` for assembled validation. It needs a clean
|
||||
committed candidate on `main` and a matching checked-in release note. If the
|
||||
actual release version is not selected, make a disposable copy on `main`,
|
||||
add a temporary matching note for an unused validation version compatible
|
||||
with the module path, and commit that copy. Run `scripts/release.sh check
|
||||
VERSION` there. Keep this fixture outside the Audita worktree. This check
|
||||
supplies the selected offline race suite, vet, formatting, Markdown and
|
||||
module checks, Linux amd64/arm64 builds, and native version identity; do
|
||||
not require a duplicate full run on the same source solely for handoff.
|
||||
4. Exercise Audita's tag-delivery wiring with a disposable annotated tag and
|
||||
controlled destination/fixtures: check the clone/event commit, native tool
|
||||
bootstrap and `ci-deliver` handoff, and product/target/asset settings. Use
|
||||
upstream delivery coverage rather than recreating generic forge tests. Use
|
||||
synthetic authentication for local fixtures; do not use production delivery
|
||||
credentials, push a tag, or publish to the hosted release service.
|
||||
Report the evidence and any live-delivery limit accurately. Neither hosted
|
||||
availability nor CI completion is a new release gate.
|
||||
5. Check completion against each child roadmap and the master's target. Report
|
||||
implementation checks, remaining upstream issues if any, and the resulting
|
||||
workspace/commit state under agent policy. Release preparation, including
|
||||
actual major tag/module-path selection, checked-in release notes, and source
|
||||
publication, remains separate. Do not claim implementation completion on
|
||||
the basis of the earlier library probes or any unresolved required behavior.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Which directory should contain selected overlays?
|
||||
|
||||
The roadmap selects native overlays, but does not give `LoadLayered` its
|
||||
required explicit overlay context. Native automatic discovery selects the main
|
||||
file during loading, so its path cannot be used to choose that context in advance.
|
||||
|
||||
- **Recommendation, used by Stage 2:** use the invocation directory as the
|
||||
overlay root (`./overlays/<name>.yml`), with or without a main file. This is
|
||||
consistent with the selected automatic glossary and PromptKit contexts and
|
||||
permits a single native load. Main-file imports still use their own context.
|
||||
- **Alternative:** expose an explicit overlay-root selector, defaulting to the
|
||||
invocation directory. This supports centralized overlays independent of the
|
||||
invocation directory at the cost of another selection to wire through all
|
||||
commands and comparison sides. If main-file-relative overlays themselves are
|
||||
required, seek a native layered-loading facility for that behavior before
|
||||
adding a second discovery/load pass. The old main-relative behavior carries
|
||||
no compatibility requirement for this release.
|
||||
@@ -2,11 +2,9 @@
|
||||
|
||||
**Updated:** 2026-11-09
|
||||
|
||||
**Status:** Design decisions are resolved across the master and all four child
|
||||
roadmaps; ready for implementation planning. Implementation and dependency
|
||||
changes remain pending. The sequence below includes common preflight and output
|
||||
preparation during CommandKit adoption, followed by glossary-specific readiness
|
||||
checks with the glossary feature.
|
||||
**Status:** Target decisions are recorded across this roadmap and its four child
|
||||
roadmaps; implementation and dependency changes remain pending. The
|
||||
[implementation plan](implementation.md) owns the sprint sequence.
|
||||
|
||||
## Objective and Document Ownership
|
||||
|
||||
@@ -20,10 +18,9 @@ ConfigKit and stages that select different glossary inputs. This is required
|
||||
feature scope alongside the library upgrades; the glossary roadmap owns the
|
||||
configuration handoff and derived runtime representations.
|
||||
|
||||
This document owns shared adoption principles, sequencing, dependency selection,
|
||||
and cross-library decisions, including the ReleaseKit adoption work below. The
|
||||
linked outlines own feature-specific outcomes, work, acceptance criteria, and
|
||||
open decisions:
|
||||
This document owns shared adoption principles, dependency selection, and
|
||||
cross-library decisions, including the ReleaseKit target below. The linked
|
||||
outlines own feature-specific outcomes and acceptance criteria:
|
||||
|
||||
| Outline | Responsibility |
|
||||
| --- | --- |
|
||||
@@ -118,7 +115,7 @@ accessor for quiet destination validation. The matching released integrations
|
||||
were reviewed together. The [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access)
|
||||
records the API contract and review evidence. The selected release set removes
|
||||
the upstream availability blocker; Audita implementation and acceptance remain
|
||||
pending under the sequence below.
|
||||
pending under the [implementation plan](implementation.md).
|
||||
|
||||
The reviewed target dependency graph includes ReleaseKit v0.9.0, but Audita's
|
||||
direct tool still uses old-path v0.4.1. The release, workflow, and validator review
|
||||
@@ -126,68 +123,6 @@ is complete, with no identified upstream blocker. The agreed
|
||||
[ReleaseKit adoption work](#releasekit-adoption-work) below remains to be
|
||||
implemented and accepted in Audita.
|
||||
|
||||
## Proposed Order of Operations
|
||||
|
||||
1. **Carry the agreed contracts into implementation planning.** Use the selected
|
||||
standard command inventory, discovery behavior, source ownership, and
|
||||
reporting and release-workflow expectations to define implementation units.
|
||||
Identify concrete upstream requests early; do not postpone CommandKit design
|
||||
until the runtime is done.
|
||||
Reconcile planned changes with the current architecture policy, especially
|
||||
preference for standard-library CLI parsing. Backend, credential, and
|
||||
concurrency ownership are resolved in the [PromptKit outline](promptkit.md):
|
||||
adopt native behavior and retire Audita's duplicate registry and policies.
|
||||
Update application-only credential rules, the finite-admission requirement,
|
||||
and other affected contracts with adopted behavior; do not
|
||||
silently treat old integration choices as permanent requirements.
|
||||
Keep stage-specific glossary inputs in view when choosing configuration and
|
||||
CLI contracts; detailed feature design and implementation follow adoption.
|
||||
2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating
|
||||
source/build requirements, CI/bootstrap assumptions, release instructions,
|
||||
and toolchain attribution. Upgrade the direct ReleaseKit tool, launcher, and
|
||||
version integration to v0.9.0, implementing the release-machinery work below.
|
||||
Inventory operator file and CLI changes for hard-cutover guidance.
|
||||
Keep implementation units focused; no intermediate public release is needed.
|
||||
3. **Coordinate the ConfigKit and PromptKit cutover.** Change both module
|
||||
identities and their exchanged types together, then implement native resource
|
||||
formats, configuration semantics, runtime checks, and standard inspection
|
||||
providers. Include the [automatic prompt-source workflow](promptkit.md#automatic-prompt-sources--resolved)
|
||||
and a shared engine loader for processing and standard inspection.
|
||||
Avoid a permanent replacement or dual configuration engine.
|
||||
Identify and remove local code made redundant by the adopted facilities as
|
||||
part of each migration, rather than leaving cleanup as an unspecified follow-up.
|
||||
4. **Integrate the selected CommandKit core and both standard integrations.**
|
||||
The upstream release gate is satisfied. Complete the designed operator
|
||||
interface using the selected v0.6.0 set, adapting Audita domain handlers and
|
||||
verifying the assembled application. Establish the named preflight package
|
||||
and its [output preparation](commandkit.md#output-resource-preparation-during-preflight--resolved),
|
||||
applying the [resolved output-failure rules](commandkit.md#output-failure-behavior--resolved).
|
||||
Resolve concrete new integration gaps upstream. This remains required scope
|
||||
for the next major release.
|
||||
5. **Add stage-specific glossary inputs.** After all four library adoptions,
|
||||
complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted
|
||||
configuration and CLI conventions to compose reusable glossary assets through
|
||||
ConfigKit, then derive Audita's runtime views for ordered stages such as a
|
||||
party pass followed by a spell pass. Remove the standalone glossary parsing
|
||||
path and extend the common preflight package with glossary-stage readiness
|
||||
checks before output preparation. This sequencing avoids designing the
|
||||
feature around interfaces that the upgrades replace.
|
||||
6. **Validate and document the assembled application.** Complete the offline
|
||||
behavioral checks from the outlines and the full Audita suite. Update canonical
|
||||
configuration, CLI, operations, integration, and internal documentation with
|
||||
implementation; provide maintained examples and hard-cutover guidance. Validate
|
||||
the adopted release workflow without publishing a release.
|
||||
7. **Prepare the next major release.** Public configuration, inspection, and CLI
|
||||
changes warrant a major release under [release policy](../policy/release.md).
|
||||
Exact numbering and publication timing remain release-preparation work. Use
|
||||
the adopted ReleaseKit workflow and selected upstream validators; document
|
||||
required operator changes without requiring a compatibility transition period.
|
||||
|
||||
Separate outlines organize responsibility; they do not make the dependency
|
||||
migration independent. The two ConfigKit import identities have distinct Go
|
||||
named types. Early upstream investigation can proceed before the dependent
|
||||
implementation stage is ready.
|
||||
|
||||
## ReleaseKit Adoption Work
|
||||
|
||||
### Workflow and Validator Selection — Resolved
|
||||
@@ -238,34 +173,25 @@ Do not duplicate these checks in profile `checks`, custom release hooks, or
|
||||
surrounding scripts. Any future local release validator requires a documented
|
||||
domain-specific justification; reusable gaps should be addressed upstream.
|
||||
|
||||
### Required Implementation and Acceptance
|
||||
### Release Integration Acceptance
|
||||
|
||||
1. Migrate the direct tool declaration and runtime `buildinfo` import together
|
||||
to `go.maximumdirect.net/releasekit` v0.9.0 so build-time version injection
|
||||
and runtime reporting use the same implementation. Remove superseded direct
|
||||
dependencies and tool registrations.
|
||||
2. Update the launcher and Woodpecker workflow from the v0.9.0
|
||||
[adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md)
|
||||
and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml).
|
||||
Include Go host-platform selection and invocation by the full tool-package
|
||||
path; a dependency upgrade alone does not update copied recipes. Keep only
|
||||
necessary repository wiring around the maintained upstream workflow.
|
||||
3. Apply the selected checks in `releasekit.json`, add the required
|
||||
`delivery.forge: "gitea"`, and retain Audita's product, production targets,
|
||||
delivery destination, and CI secret mapping. Align local validation and CI
|
||||
with the selected Go 1.27-or-newer toolchain. Include the C compiler and cgo
|
||||
prerequisites required by race detection in the maintainer setup.
|
||||
4. Remove generic launcher and bootstrap tests already covered by ReleaseKit.
|
||||
Retain focused checks for Audita's product settings, targets, destination,
|
||||
and version integration. Reconcile the release policy and runbook with the
|
||||
selected workflow and validator rationale as implementation lands; update
|
||||
attribution and link to standard upstream recovery documentation.
|
||||
5. Verify the selected validators, both production builds, version identity,
|
||||
and assembled launcher/CI wiring without publishing a release. Confirm that
|
||||
removed local checks are no longer duplicated around upstream validation.
|
||||
Hosted-delivery integration remains implementation acceptance work; the
|
||||
disposable local check below does not establish it. Adoption work does not
|
||||
authorize publishing a release.
|
||||
The direct tool and runtime version accessor use the same v0.9.0 module identity.
|
||||
The launcher and Woodpecker bootstrap follow the v0.9.0
|
||||
[adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md)
|
||||
and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml),
|
||||
including host target selection, full tool-package invocation, and prepared tag
|
||||
checkout verification. Audita retains its product, Linux production targets,
|
||||
delivery destination, and CI secret mapping, with `delivery.forge: "gitea"`.
|
||||
Local validation and CI use the selected Go 1.27-or-newer toolchain; maintainer
|
||||
setup includes the C compiler and cgo prerequisites for race detection.
|
||||
|
||||
ReleaseKit owns generic bootstrap, launcher, and selected native validation
|
||||
mechanisms. Audita retains focused evidence for its product settings, targets,
|
||||
destination, and version integration. Acceptance covers the selected validators,
|
||||
both production builds, version identity, and assembled launcher/CI wiring,
|
||||
without publishing a release. The disposable local check below is evidence for
|
||||
local candidate validation and does not establish hosted delivery. Adopted policy
|
||||
and runbook describe the selected workflow, validator rationale, and native recovery.
|
||||
|
||||
## Shared Evidence, Validation, and Completion
|
||||
|
||||
|
||||
@@ -4,7 +4,8 @@
|
||||
|
||||
**Status:** Adoption direction and automatic operator-source selection resolved;
|
||||
implementation remains pending. Follow the [master roadmap](library-adoption.md)
|
||||
for shared adoption principles, dependency identities, and sequencing.
|
||||
for shared adoption principles and dependency identities, and the
|
||||
[implementation plan](implementation.md) for sequencing.
|
||||
|
||||
## Baseline and Target
|
||||
|
||||
@@ -37,7 +38,7 @@ execution profile or make provider calls during construction.
|
||||
### Backend Concurrency Ownership — Resolved
|
||||
|
||||
Adopt PromptKit's native per-backend concurrency behavior, including backend
|
||||
defaults and supported configuration and CLI overrides. The purpose is to keep
|
||||
defaults and native configuration. The purpose is to keep
|
||||
requests within the concurrency a backend can accommodate; no separate Audita
|
||||
domain requirement has been identified for an additional limit.
|
||||
|
||||
@@ -48,10 +49,10 @@ otherwise valid PromptKit configuration. Use the shared PromptKit engine so
|
||||
proposal and validation work for the same backend share its admission control.
|
||||
Audita still owns cancellation and deterministic processing around model calls.
|
||||
|
||||
Verify the exact upstream override APIs while wiring the adopted configuration
|
||||
and CLI integrations. Update the architecture policy's finite-admission wording,
|
||||
runtime documentation, examples, and tests with implementation. Remove superseded
|
||||
behavior directly in the major release, with hard-cutover guidance.
|
||||
The selected PromptKit configuration scope does not forward ConfigKit CLI
|
||||
overrides, and request overrides do not set concurrency. Configure limits on
|
||||
native backend resources. Architecture policy, runtime documentation, examples,
|
||||
and tests describe the adopted ownership and hard cutover.
|
||||
|
||||
### Backend and Credential Ownership — Resolved
|
||||
|
||||
@@ -192,61 +193,32 @@ resolver. Include the retired view and its standard replacements in the
|
||||
hard-cutover guidance. The [CommandKit outline](commandkit.md) owns the operator
|
||||
surface and request-preview integration work.
|
||||
|
||||
### Migration Work
|
||||
### Target Request and Source Boundaries
|
||||
|
||||
1. Move to `go.maximumdirect.net/promptkit` together with ConfigKit's new types.
|
||||
Remove the old external catalog dependencies when no longer incorporated;
|
||||
retain PromptKit's built-in catalog rather than disabling it.
|
||||
2. Convert root and collection backends, profiles, and prompts to identified lists
|
||||
with explicit `id` fields. Use sibling `extends: {id: parent}` and complete
|
||||
same-ID replacement records. Typed source builders use ordered slices.
|
||||
Preserve provider settings deliberately: partial same-ID replacements no
|
||||
longer merge fields. Use exact native collection references where collections
|
||||
are selected; mounting does not rewrite stored references.
|
||||
3. Convert the seven embedded prompts into the `audita` collection and update
|
||||
maintained operator examples/fixtures for the resolved replacement workflow.
|
||||
Implement automatic operator imports above the embedded underlay through the
|
||||
shared engine loader, including explicit host and embedded filesystem contexts.
|
||||
Remove prompt version selectors and descriptive `PromptVersion` metadata from
|
||||
requests, registries, inspection, and diagnostics. Response-schema versions
|
||||
are separate and need not change. Keep domain instructions and per-call schemas;
|
||||
this adoption is not a prompt-quality rewrite. Shared instruction variables
|
||||
remain available to templates, while native operator overrides control their
|
||||
inclusion. Domain validation remains enforced after model responses.
|
||||
4. Adapt resource inspection to optional profile fields and separate backend
|
||||
inspection. These describe resources, not completed requests. Use real
|
||||
`PrepareExecution` details and `RunPrepared` for execution of the same captured
|
||||
request. Remove the curated profile view and its supporting projection code;
|
||||
do not duplicate PromptKit's full resolver or construct synthetic requests
|
||||
merely to reproduce that summary. Inspect bundled and unselected partial
|
||||
resources without requiring them to be runnable.
|
||||
5. Implement the resolved backend and credential ownership decision above.
|
||||
Replace application backend/credential configuration with native resources
|
||||
and document the hard cutover. Preserve secret-safe diagnostics using the
|
||||
library's public boundaries and Audita's domain artifact redaction; evaluate
|
||||
actual gaps with synthetic keys.
|
||||
6. Review presence semantics field by field. Null endpoint, credential-source,
|
||||
and whole provider map now allow backend defaults; explicit empty strings
|
||||
clear endpoint/credential sources. Null does not suppress the entire backend
|
||||
provider map. Sampling fields have distinct semantics. Avoid blanket null or
|
||||
zero conversion and document intentional request changes.
|
||||
7. Update captured-source accounting for list indexes and collection prefixes,
|
||||
including inherited/moved content-file origins. Preserve output-collision
|
||||
protection for consumed host documents, including automatic imports, and
|
||||
effective message files. Array positions are addresses, not durable resource
|
||||
identities.
|
||||
8. Keep self-contained embedded response schemas. The new schema rule does not
|
||||
require a bundler for Audita's current schemas. Check custom artifact-reader
|
||||
ownership only where such a reader is actually used. Preserve native retries,
|
||||
structural repair, cancellation, deadlines, and shared engine admission while
|
||||
retaining Audita's domain reconciliation and partial-success outcomes.
|
||||
PromptKit resource sources use identified lists, native sibling `extends`, and
|
||||
complete same-ID replacement records. Qualified references remain explicit.
|
||||
Audita requests, registries, inspection, and diagnostics use prompt IDs without
|
||||
obsolete prompt-version selection or labels. The existing domain instructions,
|
||||
self-contained response schemas, per-call schema and repair controls, and
|
||||
proposal/validator behavior remain distinct from resource format changes.
|
||||
|
||||
Update [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
|
||||
[runtime internals](../internal/llm-runtime.md), [prompt guidance](../internal/prompts.md),
|
||||
operator examples, diagnostics metadata documentation, and attribution with the
|
||||
implementation. Standard inspection replaces curated-only disclosure; prompts
|
||||
and provider settings may appear where the library's normal inspection exposes
|
||||
them, with native redaction. Do not accidentally promise old prompt hashes.
|
||||
Resource inspection shows native optional profile fields and backend definitions;
|
||||
prepared execution shows the completed request. Audita executes the captured
|
||||
request it prepared, without a parallel target resolver. Native field-specific
|
||||
null and presence rules govern defaults. Audita retains logical operation
|
||||
budgets, cancellation, truthful partial success, and safe diagnostics.
|
||||
|
||||
Output-collision protection accounts for consumed host documents, including
|
||||
imports, and effective source-relative `content_file` resources. Source metadata
|
||||
tracks inherited and moved values at native list-index and collection paths;
|
||||
array positions are addresses, not durable resource IDs. Native redaction governs
|
||||
standard inspection, while Audita owns its artifact redaction.
|
||||
|
||||
Canonical [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
|
||||
[runtime](../internal/llm-runtime.md), and [prompt guidance](../internal/prompts.md)
|
||||
will describe the implemented behavior and cutover, alongside updated examples
|
||||
and attribution. Standard inspection can show prompts and provider settings
|
||||
where the library exposes them; old prompt hashes are not a contract.
|
||||
|
||||
## Acceptance and Upstream Requests
|
||||
|
||||
|
||||
Reference in New Issue
Block a user