Plan the Audita adoption sprint
This commit is contained in:
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.
|
||||
Reference in New Issue
Block a user