Plan the Audita adoption sprint
This commit is contained in:
@@ -4,9 +4,9 @@
|
|||||||
|
|
||||||
**Status:** Adoption target and design decisions resolved; the upstream release
|
**Status:** Adoption target and design decisions resolved; the upstream release
|
||||||
gate is satisfied. Implementation remains pending. The
|
gate is satisfied. Implementation remains pending. The
|
||||||
[master roadmap](library-adoption.md) owns shared direction, exact dependency
|
[master roadmap](library-adoption.md) owns shared direction and exact dependency
|
||||||
revisions, and sequencing; ConfigKit and
|
revisions; the [implementation plan](implementation.md) owns sequencing. See the
|
||||||
PromptKit contracts are developed in [their](configkit.md) [outlines](promptkit.md).
|
[ConfigKit](configkit.md) and [PromptKit](promptkit.md) outlines for their contracts.
|
||||||
|
|
||||||
## Baseline and Target
|
## 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
|
inputs; representative validator candidates can come from maintained fixtures
|
||||||
without running proposal inference as part of request construction.
|
without running proposal inference as part of request construction.
|
||||||
|
|
||||||
Establish runtime and request construction first, then wire preview and
|
All three capabilities are required adoption scope. Address concrete integration
|
||||||
validation, followed by smoke commands and assembled-CLI verification. All are
|
blockers upstream rather than silently omitting standard capabilities.
|
||||||
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
|
For standard CommandKit commands passed through by Audita, provide a concise
|
||||||
link to the upstream documentation for the adopted version. Upstream owns their
|
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
|
own selectors, request construction, domain inputs, and application-specific
|
||||||
behavior. Apply this documentation boundary to the whole standard command suite.
|
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
|
The native `app` and PromptKit configuration scopes are distinct. Both sides of
|
||||||
released dependency set when implementing this outline.
|
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,
|
Audita supplies typed process inputs, domain request construction, preflight,
|
||||||
streams, and exit behavior against standard declarations. Record intentional
|
and output-session coordination. [Glossary readiness](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
|
||||||
migrations rather than recreating the old parser around CommandKit.
|
is part of that shared phase. Standard inspection remains independent of
|
||||||
2. Establish shared loaders and scopes using the native ConfigKit and PromptKit
|
processing inputs. Canonical Audita documentation owns application-specific
|
||||||
integrations. Use the same engine-loading path for processing and every
|
behavior and the hard cutover; standard commands link to the adopted upstream
|
||||||
PromptKit inspection, preview, validation, and smoke command, following the
|
reference. Exact selected dependencies and notices belong in attribution.
|
||||||
[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.
|
|
||||||
|
|
||||||
## Acceptance and Upstream Requests
|
## Acceptance and Upstream Requests
|
||||||
|
|
||||||
|
|||||||
@@ -2,8 +2,9 @@
|
|||||||
|
|
||||||
**Updated:** 2026-11-09
|
**Updated:** 2026-11-09
|
||||||
|
|
||||||
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
|
**Status:** Target decisions resolved; implementation pending. The
|
||||||
agreed adoption policy, reviewed versions, shared sequencing, and completion.
|
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
|
||||||
|
the [implementation plan](implementation.md) owns sequencing.
|
||||||
|
|
||||||
## Baseline and Target
|
## 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
|
source record. Explicit-file errors and failures loading a selected discovered
|
||||||
file remain terminal.
|
file remain terminal.
|
||||||
|
|
||||||
### Migration Work
|
### Target Boundaries
|
||||||
|
|
||||||
1. Move imports to `go.maximumdirect.net/configkit` with the coordinated
|
The application uses the `go.maximumdirect.net/configkit` module and native
|
||||||
PromptKit cutover. Raise the toolchain as specified by the master roadmap.
|
recorded resolution, discovery, source diagnostics, and safe effective output.
|
||||||
Replace `Resolution.Record` uses with the appropriate dedicated recording
|
Source composition and inheritance precede typed decoding and explicit CLI
|
||||||
method; review affected metadata and diagnostics APIs, not only compilation.
|
assignment; application resolution and validation follow. CLI assignments do
|
||||||
Relevant renamed concepts include `EntryInfo`, `Sensitive`, `LayerMain`,
|
not repair earlier decoding failures, change inheritance relationships, or
|
||||||
version evidence, and destination fallback. Typed `Secret` and its field tag
|
propagate parent edits through resolved children. Native source provenance uses
|
||||||
retain their spelling.
|
`main` in place of `base`. Genuine source-root controls use `config:`.
|
||||||
2. Adopt the native lifecycle: source composition and inheritance, typed decoding,
|
|
||||||
explicit CLI assignments, then application resolution and validation. CLI
|
PromptKit [owns backend and credential resources](promptkit.md#backend-and-credential-ownership--resolved).
|
||||||
assignments do not repair earlier decoding failures, alter inheritance
|
Audita's v3 schema has no separate backend or LLM credential registry. Native
|
||||||
relationships, or propagate parent edits through already resolved children.
|
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
|
||||||
Update the current loading-order explanation and realistic integration tests.
|
remain independent of main application-file discovery.
|
||||||
3. Migrate genuine source-root control blocks to `config:` where present.
|
|
||||||
Implement the version-3 application schema and hard cutover above. Distinguish
|
The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
|
||||||
application schema versions from source version evidence; do not impose
|
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
|
||||||
headers on every fragment merely because the API supports them.
|
and [optional stage identity](glossary-stages.md#stage-identity-and-attribution--resolved).
|
||||||
4. Use identified collections where records have meaningful identity. ConfigKit
|
Glossary definitions use native composition, [default underlay sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved),
|
||||||
upsert replaces matching records in full; inspection follows registered
|
and [collection-scoped identity](glossary-stages.md#entry-identity--resolved).
|
||||||
identities through movement, while list diffs remain atomic. Preserve ordinary
|
Pipeline stages remain an ordinary ordered list, including repetitions and
|
||||||
ordered/repeated pipeline stages and explicit empty-pipeline semantics:
|
explicit empty-pipeline behavior. The application supplies domain resolution
|
||||||
these express Audita domain behavior, so uniqueness/upsert is inappropriate.
|
rules within the native lifecycle, with no second runtime defaulting pass.
|
||||||
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.
|
|
||||||
|
|
||||||
## Documentation and Acceptance
|
## 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
|
precedence over overlapping protection. Empty collections are permitted, with
|
||||||
Audita preflight rejecting empty glossary stages. Design decisions are resolved;
|
Audita preflight rejecting empty glossary stages. Design decisions are resolved;
|
||||||
implementation is pending. The
|
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
|
## 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
|
Keep the nonempty glossary-stage check in Audita preflight rather than ConfigKit's
|
||||||
configuration-validation callbacks.
|
configuration-validation callbacks.
|
||||||
|
|
||||||
Implement this phase in an expressly named `internal/framework/preflight`
|
The shared `internal/framework/preflight` package owns this phase.
|
||||||
package, established during CommandKit adoption and extended by this feature.
|
|
||||||
Accept fully resolved configuration and the domain inputs needed for
|
Accept fully resolved configuration and the domain inputs needed for
|
||||||
readiness checks through ordinary Go functions and concrete inputs. Return
|
readiness checks through ordinary Go functions and concrete inputs. Return
|
||||||
errors identifying the affected stage and reason; CLI presentation remains with
|
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
|
the field inventory into multiple developer documents. This documentation work
|
||||||
is part of feature acceptance, not an optional follow-up.
|
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
|
The glossary feature uses the adopted ConfigKit and CommandKit conventions and
|
||||||
before final release validation and preparation. This lets the feature use the
|
the shared preflight/output-session boundary. It replaces the standalone glossary
|
||||||
adopted configuration and CLI conventions and avoids adapting it twice. Keep the
|
input and parsing path with typed, composed configuration. Runtime consumers
|
||||||
requirement visible during library design without expanding those migrations
|
receive derived per-stage views from that handoff; reports identify the stage
|
||||||
into feature implementation. CommandKit adoption establishes the common preflight
|
and configuration inspection explains its effective selections and origins.
|
||||||
package and output preparation; this feature adds glossary-specific readiness
|
Consumed glossary sources participate in output-collision protection. Maintained
|
||||||
checks to that phase.
|
examples and hard-cutover guidance describe the new configuration contract.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Acceptance Direction
|
## 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
|
**Updated:** 2026-11-09
|
||||||
|
|
||||||
**Status:** Design decisions are resolved across the master and all four child
|
**Status:** Target decisions are recorded across this roadmap and its four child
|
||||||
roadmaps; ready for implementation planning. Implementation and dependency
|
roadmaps; implementation and dependency changes remain pending. The
|
||||||
changes remain pending. The sequence below includes common preflight and output
|
[implementation plan](implementation.md) owns the sprint sequence.
|
||||||
preparation during CommandKit adoption, followed by glossary-specific readiness
|
|
||||||
checks with the glossary feature.
|
|
||||||
|
|
||||||
## Objective and Document Ownership
|
## 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
|
feature scope alongside the library upgrades; the glossary roadmap owns the
|
||||||
configuration handoff and derived runtime representations.
|
configuration handoff and derived runtime representations.
|
||||||
|
|
||||||
This document owns shared adoption principles, sequencing, dependency selection,
|
This document owns shared adoption principles, dependency selection, and
|
||||||
and cross-library decisions, including the ReleaseKit adoption work below. The
|
cross-library decisions, including the ReleaseKit target below. The linked
|
||||||
linked outlines own feature-specific outcomes, work, acceptance criteria, and
|
outlines own feature-specific outcomes and acceptance criteria:
|
||||||
open decisions:
|
|
||||||
|
|
||||||
| Outline | Responsibility |
|
| 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)
|
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
|
records the API contract and review evidence. The selected release set removes
|
||||||
the upstream availability blocker; Audita implementation and acceptance remain
|
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
|
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
|
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
|
[ReleaseKit adoption work](#releasekit-adoption-work) below remains to be
|
||||||
implemented and accepted in Audita.
|
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
|
## ReleaseKit Adoption Work
|
||||||
|
|
||||||
### Workflow and Validator Selection — Resolved
|
### 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
|
surrounding scripts. Any future local release validator requires a documented
|
||||||
domain-specific justification; reusable gaps should be addressed upstream.
|
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
|
The direct tool and runtime version accessor use the same v0.9.0 module identity.
|
||||||
to `go.maximumdirect.net/releasekit` v0.9.0 so build-time version injection
|
The launcher and Woodpecker bootstrap follow the v0.9.0
|
||||||
and runtime reporting use the same implementation. Remove superseded direct
|
[adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md)
|
||||||
dependencies and tool registrations.
|
and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml),
|
||||||
2. Update the launcher and Woodpecker workflow from the v0.9.0
|
including host target selection, full tool-package invocation, and prepared tag
|
||||||
[adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md)
|
checkout verification. Audita retains its product, Linux production targets,
|
||||||
and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml).
|
delivery destination, and CI secret mapping, with `delivery.forge: "gitea"`.
|
||||||
Include Go host-platform selection and invocation by the full tool-package
|
Local validation and CI use the selected Go 1.27-or-newer toolchain; maintainer
|
||||||
path; a dependency upgrade alone does not update copied recipes. Keep only
|
setup includes the C compiler and cgo prerequisites for race detection.
|
||||||
necessary repository wiring around the maintained upstream workflow.
|
|
||||||
3. Apply the selected checks in `releasekit.json`, add the required
|
ReleaseKit owns generic bootstrap, launcher, and selected native validation
|
||||||
`delivery.forge: "gitea"`, and retain Audita's product, production targets,
|
mechanisms. Audita retains focused evidence for its product settings, targets,
|
||||||
delivery destination, and CI secret mapping. Align local validation and CI
|
destination, and version integration. Acceptance covers the selected validators,
|
||||||
with the selected Go 1.27-or-newer toolchain. Include the C compiler and cgo
|
both production builds, version identity, and assembled launcher/CI wiring,
|
||||||
prerequisites required by race detection in the maintainer setup.
|
without publishing a release. The disposable local check below is evidence for
|
||||||
4. Remove generic launcher and bootstrap tests already covered by ReleaseKit.
|
local candidate validation and does not establish hosted delivery. Adopted policy
|
||||||
Retain focused checks for Audita's product settings, targets, destination,
|
and runbook describe the selected workflow, validator rationale, and native recovery.
|
||||||
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.
|
|
||||||
|
|
||||||
## Shared Evidence, Validation, and Completion
|
## Shared Evidence, Validation, and Completion
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,8 @@
|
|||||||
|
|
||||||
**Status:** Adoption direction and automatic operator-source selection resolved;
|
**Status:** Adoption direction and automatic operator-source selection resolved;
|
||||||
implementation remains pending. Follow the [master roadmap](library-adoption.md)
|
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
|
## Baseline and Target
|
||||||
|
|
||||||
@@ -37,7 +38,7 @@ execution profile or make provider calls during construction.
|
|||||||
### Backend Concurrency Ownership — Resolved
|
### Backend Concurrency Ownership — Resolved
|
||||||
|
|
||||||
Adopt PromptKit's native per-backend concurrency behavior, including backend
|
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
|
requests within the concurrency a backend can accommodate; no separate Audita
|
||||||
domain requirement has been identified for an additional limit.
|
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.
|
proposal and validation work for the same backend share its admission control.
|
||||||
Audita still owns cancellation and deterministic processing around model calls.
|
Audita still owns cancellation and deterministic processing around model calls.
|
||||||
|
|
||||||
Verify the exact upstream override APIs while wiring the adopted configuration
|
The selected PromptKit configuration scope does not forward ConfigKit CLI
|
||||||
and CLI integrations. Update the architecture policy's finite-admission wording,
|
overrides, and request overrides do not set concurrency. Configure limits on
|
||||||
runtime documentation, examples, and tests with implementation. Remove superseded
|
native backend resources. Architecture policy, runtime documentation, examples,
|
||||||
behavior directly in the major release, with hard-cutover guidance.
|
and tests describe the adopted ownership and hard cutover.
|
||||||
|
|
||||||
### Backend and Credential Ownership — Resolved
|
### 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
|
hard-cutover guidance. The [CommandKit outline](commandkit.md) owns the operator
|
||||||
surface and request-preview integration work.
|
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.
|
PromptKit resource sources use identified lists, native sibling `extends`, and
|
||||||
Remove the old external catalog dependencies when no longer incorporated;
|
complete same-ID replacement records. Qualified references remain explicit.
|
||||||
retain PromptKit's built-in catalog rather than disabling it.
|
Audita requests, registries, inspection, and diagnostics use prompt IDs without
|
||||||
2. Convert root and collection backends, profiles, and prompts to identified lists
|
obsolete prompt-version selection or labels. The existing domain instructions,
|
||||||
with explicit `id` fields. Use sibling `extends: {id: parent}` and complete
|
self-contained response schemas, per-call schema and repair controls, and
|
||||||
same-ID replacement records. Typed source builders use ordered slices.
|
proposal/validator behavior remain distinct from resource format changes.
|
||||||
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.
|
|
||||||
|
|
||||||
Update [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
|
Resource inspection shows native optional profile fields and backend definitions;
|
||||||
[runtime internals](../internal/llm-runtime.md), [prompt guidance](../internal/prompts.md),
|
prepared execution shows the completed request. Audita executes the captured
|
||||||
operator examples, diagnostics metadata documentation, and attribution with the
|
request it prepared, without a parallel target resolver. Native field-specific
|
||||||
implementation. Standard inspection replaces curated-only disclosure; prompts
|
null and presence rules govern defaults. Audita retains logical operation
|
||||||
and provider settings may appear where the library's normal inspection exposes
|
budgets, cancellation, truthful partial success, and safe diagnostics.
|
||||||
them, with native redaction. Do not accidentally promise old prompt hashes.
|
|
||||||
|
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
|
## Acceptance and Upstream Requests
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user