audita/docs/roadmap/implementation.md

# 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.