promptkit/docs/roadmap/implementation.md

# Audit Remediation Implementation Plan

## Scope And Execution Model

Implement the selected end state in [audit-remediation.md](audit-remediation.md)
against production baseline `e85ea2d`. Its workstreams, accepted catalog
decisions, compatibility choices, and historical assessment evidence remain the
background authority. This plan owns implementation order and stage outcomes.
All stages are initially pending; all 34 catalog entries are included.

Follow the stages in order as one end-to-end sprint. Each stage is sized as a
focused Luna coding-agent prompt. Intermediate stages may leave callers/tests
unmigrated or the repository temporarily unable to compile. Do not introduce
transitional adapters, duplicate implementations, extra public APIs, or separate
publication/review gates merely to make each intermediate stage coherent.
Record deferred checks and run them when the affected path becomes runnable;
the final state must compile, satisfy the selected behavior, and pass validation.

Read [development guidance](../development.md) and its applicable policy/contract
documents. In particular follow agents, architecture, testing, documentation,
and [ADR 0001](../adr/0001-configuration-boundary.md). Use the graph tools for
code discovery and inspect actual callers before changing signatures/deleting
helpers. Preserve unrelated work. Follow the local commit policy for completed
units, reporting temporary incompleteness accurately. This sprint does not
authorize pushing, tagging, publishing, or selecting a release version.

### Shared Implementation Rules

- ConfigKit owns composition, immediate Mapping capture, and raw-source errors.
  PromptKit interprets/validates the final handoff. Operator provenance remains
  available but is not analyzed during execution or used as another validator.
- Preserve public contracts except the accepted artifact ownership,
  self-contained schema, and convenience-source value changes. Retain runtime
  override support, template recognition scope, status-only retries, capacity
  policy, and privacy. Definition hashes may change as documented opaque values.
- Private names below describe selected seams, not new public compatibility
  promises. Keep the public facade thin and internal dependencies one-way.
- Tests protect meaningful behavior, not helper structure, exact allocation
  counts, old hash encodings, incidental independent-error ordering, or complete
  diagnostic text. Use existing real internal collaborators and offline external
  doubles. Do not duplicate ConfigKit's raw-source validation suite.
- Include the owning GoDoc/documentation with its behavior change. The final
  documentation stage reconciles omissions; it is not a reason to describe
  incomplete behavior as implemented earlier.
- Stage checks below are focused development checks, not new recurring release
  gates. Reuse successful checks on unchanged content. Do not run the complete
  suite after every stage. No provider calls, credentials, external publication,
  generalized benchmark framework, or human approvals are required between stages.

## Stage 1: Select The Maintainer Toolchain

**Catalog:** 1. **Scope:** environment selection and contributor guidance only.

1. Inspect the current tree/toolchain selection. Put the newest already available
   local Go binary directory first on PATH and set `GOTOOLCHAIN=local` for the
   sprint. The assessment found Go 1.27.3 in the module toolchain cache; use it
   unless a newer local installation is now available. Set `GOWORK=off` for
   repository-isolated validation, without prohibiting consumer workspaces.
2. Record `go version`. Keep `go 1.27.0` unchanged for the assessed series/patch;
   follow existing release policy if a genuinely newer series is selected.
   Do not raise the consumer minimum merely for a validation patch.
3. Clarify ordinary development selection in `docs/development.md`, linking to
   the existing release/toolchain policy. Reuse the roadmap's focused advisory
   reassessment unless changed evidence makes another check necessary.

**Validation/outcome:** The selected toolchain runs and its version is recorded.
No new installation, vulnerability gate, consumer advisory, or dependency update
is needed for the assessed environment.

Completion: selected the locally available Go 1.27.3 toolchain (`go version
go1.27.3 linux/amd64`) with `GOTOOLCHAIN=local` and `GOWORK=off` for isolated
validation. The module minimum remains Go 1.27.0; contributor guidance now
describes local toolchain selection.

## Stage 2: Remove Convenience Source Conversion

**Catalog:** 3, 5. **Files:** `profiles.go`, `backends.go`, `provider_values.go`,
source-helper GoDoc and source/construction contract tests.

1. Assign `config.ExtraParams` directly into each helper's ordinary fields map;
   let the existing final `configkit.Mapping` call capture it immediately.
   Preserve optional-field projection, ordering, and the `[]any` record wrapper.
2. Remove `providerMapForMapping`, its recursive converter, number placeholder,
   and the resulting unused file/imports. Do not replace them with validation,
   memoization, precision checking, or another clone.
3. Exercise both helpers through engine loading with supported nested built-ins,
   mutation after source creation, and representative formerly converted types
   and cyclic values that ConfigKit reports when the source is consumed.
4. Explain ConfigKit-supported forms and caller-selected numeric conversion in
   GoDoc/consumer guidance. Runtime overrides retain their separate value rules.

**Validation/outcome:** Focused source/construction tests establish immediate
capture and deferred upstream diagnostics, not acceptance of `json.Number`,
typed containers, named scalars, or nested pointers by the removed adapter.

Completion: convenience sources pass provider maps directly to ConfigKit;
the converter was removed. Focused source and construction tests passed with
Go 1.27.3, including nested capture and deferred unsupported/cyclic errors.

## Stage 3: Represent The Owning Error Operation

**Catalog:** 7, first part. **Files:** use-case error/runner/preparation boundaries.

1. Introduce an internal `OperationError` containing `Category error` and
   `Cause error`. Implement ordinary contextual formatting, `Unwrap` returning
   the cause, and `Is` matching the owning category; retain safe existing cause
   formatting rather than adding raw request/provider data.
2. Use it at the artifact, render, generation, validation, and resource lookup
   boundaries that currently add operation sentinels. Select genuine prompt/
   profile not-found categories at their owning lookup boundary, distinguishing
   them from other repository load failures. Retain existing request and
   credential classifications and nested cause identity. For generation request
   construction, use the direct preparation wrapper introduced in Stage 6,
   not a whole-chain match that can mistake a child client's error for this
   operation's preparation failure.
3. Expose this type only internally to facade translation. Do not add a public
   error taxonomy or infer the owner from the deepest matching sentinel.

**Validation/outcome:** Focused internal cases establish the explicit outer
category and matchable cause. Finish facade behavior in Stage 4; do not add
temporary mapping paths just for this intermediate stage.

Completion: operation errors retain their owning category and original cause,
including direct prompt/profile lookup categories. Focused use-case tests pass
on Go 1.27.3. Public projection and built-in preparation classification remain
for their respective later units.

## Stage 4: Preserve Categories Through Public Error Projection

**Catalog:** 7, completion. **Files:** `errors.go` and public error contracts/tests.

1. Select the outer operation category before searching arbitrary nested causes
   for public categories or capacity/provider/retry-exhaustion projections.
   Keep the mapping of unclassified existing errors where still applicable.
2. Preserve specialized public error types and their fields, redaction, and
   retry counts. Project them without losing the owning category or original
   injected cause; use wrapping/joining as needed, not category exclusivity.
   A child's existing public error remains matchable without becoming the
   parent's sole classification.
3. Add public nested-engine regressions: a valid parent client and artifact
   reader each return a child missing-prompt error. Check the parent category,
   exact child cause, and legitimate direct not-found behavior. Include
   representative specialized error composition so the earlier early-return
   branches cannot bypass the owner.

**Validation/outcome:** Root error tests and relevant use-case/generation tests
preserve `errors.Is`/`errors.As`, existing capacity metadata, exhaustion and
provider projections, and cancellation identity.

Completion: public projection preserves the owning operation alongside nested
causes and specialized projections. Root and generation tests pass on Go 1.27.3;
two use-case preparation-classification tests await the direct preparation
marker specified below.

## Stage 5: Retain Successful-Response Read Failures

**Catalog:** 8. **Files:** `internal/llm/openai_compatible_client.go` and focused
HTTP/public smoke tests.

1. Record actual non-EOF errors from the response reader beneath the existing
   limited reader. Keep this a small private wrapper, not a new reader framework.
2. At initial decoding and final EOF verification, retain observed context
   precedence and the existing size-overflow classification; otherwise wrap an
   actual reader failure using redacted `requestFailedError` so its cause remains
   inspectable. Distinguish reader-returned errors from parser-created errors.
3. Preserve malformed JSON/type/framing errors, EOF-truncated JSON, extra values,
   and size overflow as malformed response. Do not add transport retries.
4. Cover interrupted initial decoding and complete JSON followed by a failing
   read, including a reader returning bytes and an error together. Check
   transport cause/redaction and diagnostic failure classification.

**Validation/outcome:** Relevant llm tests plus focused public execution/smoke
cases establish both failure locations and unchanged genuine malformed behavior.

Completion: successful-response body read failures retain their redacted
transport cause, including errors returned with bytes. The llm suite and focused
public execution and smoke classification tests pass on Go 1.27.3.

## Stage 6: Mark Built-In Diagnostic Preparation Failure

**Catalog:** 9. **Files:** generation evidence/coordinator and smoke orchestration.

1. Add internal `GenerationEvidence.PreparationFailed bool`. Set it only when
   built-in `PrepareGeneration` fails before attempts; do not expose it publicly.
   Wrap that same return in an internal generation `PreparationError` with its
   cause so ordinary `Generate` also carries direct preparation provenance.
   `wrapGenerationError` recognizes that direct wrapper, not a nested child's
   sentinel/type, to select invalid-request rather than generation failure.
2. After caller-cancellation handling, let inference diagnostics use that marker
   to return an error matching use-case/public `ErrInvalidRequest`, preserving
   the preparation cause instead of publishing a completed failure report.
3. Preserve injected-client errors and intentional completed no-dispatch reports
   for missing required credentials/capacity, unsupported and inapplicable work.
   Neither sentinel matching alone nor an empty attempt slice identifies stage.

**Validation/outcome:** A reserved `Execution.ExtraParams["model"]` override
fails with the public invalid-request category and zero dispatch. Existing
provider rejection, missing-key, capacity, injected, and cancellation tests
retain their respective outcomes.

## Stage 7: Bound Authentication Recognition And Report Overflow

**Catalog:** 2. **Files:** current authentication probe, public/domain smoke reasons.

1. Define a named internal 1 MiB allowance and read no more than allowance plus
   one byte for HTTP 200 account recognition. Enforce actual bytes irrespective
   of declared length; detect overflow before JSON parsing and close without
   draining. Preserve the body-independent handling of 401 and other statuses.
2. Add matching public/domain
   `SmokeTestReasonAuthenticationResponseLimitExceeded` constants with value
   `authentication_response_limit_exceeded`. Report overflow with existing
   `ExecutionFailureOther`, unknown acceptance, available HTTP/timing evidence,
   and a completed report with nil Go error unless caller cancellation applies.
3. Preserve privacy, anonymous probing, and ordinary observer isolation. No new
   report Boolean, failure enum, public budget knob, or inference limit is added.

**Validation/outcome:** Focused authentication/public tests cover exact limit,
limit plus one, missing/inaccurate lengths, malformed bounded bodies, closure,
401 without reading, cancellation, and redacted explicit overflow. Keep this
fix independent of the later protocol relocation.

## Stage 8: Correct Artifact Result Ownership

**Catalog:** 4. **Files:** public ArtifactReader GoDoc, adapter and ownership tests.

1. State that successful `Read` transfers the returned artifact and mutable body
   storage to PromptKit. The reader stops mutating it through retained aliases;
   private buffers may be reused only when the returned storage is independent.
2. Keep the signature and defensive adapter copy. Update any fixtures relying
   on immediate reuse of returned mutable buffers to honor the selected contract.
3. Add focused concurrent preparation coverage using independently returned
   storage; retain adapter mutation isolation and cause propagation.

**Validation/outcome:** Race-enabled focused artifact/preparation tests follow
the accepted handoff, without promising safety for contract-violating readers.
Explain migration in consumer guidance; no borrowing/release protocol is added.

## Stage 9: Detach Prepared Ownership And Session Storage

**Catalog:** 16, 18. **Files:** runner/prepared state and domain session normalization.

1. Allocate one private non-zero-sized identity object per runner construction.
   Store its immutable pointer in prepared handles instead of `*Runner` and
   compare tokens for owner validation. Namespace views keep the same runner.
2. Keep the token after use/discard; preserve mutex-protected ready/claimed/
   discarded transitions, payload clearing, foreign-owner check order, and
   independent details. Do not create mutable owner-field synchronization work.
3. Clone each accepted nonempty normalized session string with `strings.Clone`
   after existing validation. Do not cap or otherwise reinterpret the raw input.

**Validation/outcome:** Existing and focused race tests cover foreign engines,
same-engine views, one-shot/concurrent claim/discard and details after use.
Session Unicode/trim/content/wire/hash tests stay unchanged in meaning. Reference
analysis, not a GC-timing assertion, establishes that the token retains no runner.

## Stage 10: Declare Validation Preparation As The Internal Dependency

**Catalog:** 21, interface part. **Files:** validator constructors, engine Options,
runner constructors, and their test doubles.

1. Store/accept `validate.ValidationPreparer` where engine/runner execution needs
   preparation. Remove the runtime assertion that discovered this requirement.
2. Return concrete validator pointers from internal constructors so direct
   validation callers still have `Validate`. Retain the separate direct
   `Validator` interface where actually consumed; do not expose a new public API.
3. Migrate applicable doubles to the declared interface. Replace the former
   validation-only runtime-rejection test with meaningful preparation/nil-plan
   behavior. Preserve nil-validator no-op and nil-plan error handling.

**Validation/outcome:** Inventory affected call sites and migrate them without
compatibility adapters. Run applicable validation/preparation tests when this
signature change is wired; temporary compilation gaps may continue into Stage 11.

## Stage 11: Share Root Loading And Schema Compilation

**Catalog:** 6, 21, compilation part. **Files:** `internal/validate` implementations.

1. Keep host-file and `fs.FS` root resolution/loading adapters, including contained
   paths, single-file sources, escaped resource URLs, context checks, exact JSON
   numbers, one-document decoding, and existing root dialect validation.
2. Share `compileSchemaDocument(ctx, resourceURL, document)` for compiler creation,
   Draft2020 selection, AddResource, contextual errors, and compilation. Install
   a context-aware loader that returns an actionable external-resource error
   without reading any other file or network resource. Keep bundled metaschemas
   and compiler URI/ID/anchor resolution intact.
3. Route both prepared and both direct schema paths through it. Prepared plans
   retain the root and executor; direct validation reaches compilation only
   after decoding the output instance. Remove obsolete external loaders rather
   than leaving an alternate external-loading path.

**Validation/outcome:** Retain independent root-source, cancellation, precision,
framing, containment, and freezing cases. External-reference successes become
expected errors. Root compilation alone is intentionally not the completed
self-containment remedy; Stage 12 checks otherwise unused schema declarations.

## Stage 12: Check Declared Schema Locations Through The Compiler

**Catalog:** 6, 21, resource-policy completion. **Scope:** schema-location traversal.

1. Add one private traversal of schema-bearing locations in the decoded document.
   Compile the root and each located schema using the same compiler/cache and
   retrieval URL plus escaped JSON-pointer fragment. Preserve the compiled root
   as the executor used for actual validation; do not rewrite/bundle the document.
2. Use each compiled schema's exported `DraftVersion` to select the applicable
   pinned-dependency location table. This delegates embedded-resource dialect
   resolution to the compiler rather than assuming the root dialect everywhere.
   Visit object/Boolean schemas at the applicable locations, not property-name
   dependency arrays or arbitrary example/annotation objects.
3. Match jsonschema 6.0.2 `draft.go` positions: Draft4 includes `definitions/*`,
   `not`, `allOf/[]`, `anyOf/[]`, `oneOf/[]`, `properties/*`,
   `additionalProperties`, `patternProperties/*`, `items`, `items/[]`,
   `additionalItems`, and `dependencies/*`. Draft6 adds `propertyNames`/`contains`;
   Draft7 adds `if`/`then`/`else`; Draft2019 adds `$defs/*`,
   `dependentSchemas/*`, `unevaluatedProperties`, `unevaluatedItems`,
   `contentSchema`; Draft2020 adds `prefixItems/[]`. Use the dependency's inherited
   positions without broadening its dialect acceptance. Document this pinned
   relationship locally; no new public dialect matrix is introduced.
4. Escape pointer segments (`~`, `/`) and URI fragments correctly. Check context
   around traversal/compiler calls. Do not implement a parallel URI resolver,
   lexical reference ban, generic schema engine, or new schema-size restriction.

**Validation/outcome:** An unused `$defs` external reference fails, while literal
`$ref` keys in examples/default data do not become schemas. Cover fragment and
anchor references, explicit/embedded IDs, recursive/dynamic references, escaped
keys, and embedded-resource dialect distinctions. Keep independent valid/invalid
instances; do not manufacture expectations with the traversal under test.

## Stage 13: Verify Public Schema Wiring And Native Submission

**Catalog:** 6, 15, 21; schema-file half of 32.

1. Add focused public `WithSchemaFile` construction and Prepare/Validate cases
   with real temporary files, last-valid-option/source replacement, and relevant
   missing-file/directory errors. Keep source-specific internal tests independent.
2. Add offline wire coverage that a self-contained schema, including internal
   definitions, reaches native structured output without external file loading.
   External references fail before dispatch; prepared validation remains frozen
   after source mutation/removal. Do not assert provider-side enforcement.
3. Reduce private `fileSource` to `(fs.FS, string, error)` and its caller to the
   used results. Retain the actual directory calculation, checks, and DirFS.
4. Align schema/consumer/internal documentation with self-contained resources,
   the remaining root-source options, and direct/prepared behavior.

**Validation/outcome:** Focused public preparation/validation/wire and internal
validate/engine tests finish the schema transition. No local-only mode, bundler,
new dialect, or release/publication prerequisite is introduced.

## Stage 14: Merge Provider Maps Into One Owned Lower Copy

**Catalog:** 19. **Files:** configuration targets and focused overlay tests.

1. Copy the lower map once with the existing compatible ownership boundary.
   Recurse into that owned result for overlapping built-in maps rather than
   calling the full cloning entry point for each descendant.
2. Copy upper replacement values where needed; retain null/array replacement,
   empty-map behavior, accepted types, errors, and isolation. Do not merge runtime
   override maps or introduce a new combined-map size restriction.
3. Keep the merge policy specific to backend defaults plus profile values,
   separate from ConfigKit composition/inheritance.

**Validation/outcome:** Focused configuration cases cover recursive overlap,
disjoint keys, nulls, arrays, and input mutation. Repeat the roadmap's chain/
width/disjoint baseline after implementation and record actual allocations/work;
do not assert exact benchmark thresholds as tests.

## Stage 15: Centralize Trusted JSON Clone Ownership

**Catalog:** 24. **Files:** `convert.go`, `internal/jsonvalue`, projection tests.

1. Provide internal `CloneTrusted(any) any` for detached copies of already accepted
   values. Route facade nested-value projection through this owner and remove
   the facade's reflection traversal responsibility.
2. Preserve its existing concrete scalar/container/pointer/nil and fast-path
   behavior, exact numbers, schema empty keys, and caller ownership. Audit callers
   before changing helper signatures. Do not normalize these values as fresh input.
3. Keep fallible bounded `Copy`/`CopyMap` acceptance policies distinct. Share only
   matching primitives; two small walkers are preferable to a configurable
   reflection framework. No panic, rejection, silent zero value, or swallowed
   copy error is added to an infallible projection.

**Validation/outcome:** Relevant JSON-value and facade client/prepared/inspection
mutation tests use independently specified expectations. Include distinguishing
nil/type/schema-key cases; source conversion from Stage 2 must not reappear here.

## Stage 16: Stop Recopying Growing Condition Evidence

**Catalog:** 10. **Files:** prompt requirements evaluation and focused tests.

1. Treat intermediate missing-variable/content-input sets as owned by their
   evaluation result. Transfer nil sets and insert the smaller set's members
   into the larger owned set instead of copying both into a new map.
2. Preserve unknown/unsupported/input-name flags and later operand value/truth
   checks; verify no caller retains an independent set snapshot that is mutated.
3. Add representative left-heavy conditions and set/flag outcomes, keeping sorted
   deduplicated results, partial discovery, and cancellation intact.

**Validation/outcome:** Requirements tests protect classifications and independent
rendering comparisons. Source work counts or focused measurements demonstrate
removal of the identified growing-copy pattern; no grammar or expression limit
changes, universal complexity promise, or allocation-count assertion is added.

## Stage 17: Share Requirement Branch Orchestration

**Catalog:** 23. **Files:** internal prompt requirement traversal/evaluation.

1. Factor the common `parse.BranchNode` sequence for If/With: inactive traversal,
   condition evaluation, then/else reachability, dependency-delta comparison,
   and limitation recording. Handle With's changed body dot and unchanged else
   dot explicitly; do not make the scopes interchangeable.
2. Keep recognition/evaluation and evidence/result responsibilities separately
   readable, sharing recognized command-shape helpers only where they genuinely
   match. Preserve scope entry/exit around named templates and skipped paths.
3. Do not combine this partial inspector with the real template executor or
   introduce a generic AST visitor/interpreter framework.

**Validation/outcome:** Existing node-specific tests and independent Go-renderer
comparisons retain known/skipped/unknown outcomes, inactive computed names,
optional index behavior, root access, and meaningful incompleteness.

## Stage 18: Add Bounded Diagnostic Prefix Encoding

**Catalog:** 17, encoding primitive. **Files:** repair formatter private helpers/tests.

1. Provide bounded normalization of the potentially useful prefix of one
   diagnostic. Preserve `strings.ToValidUTF8` replacement behavior, including
   runs of invalid bytes, without first normalizing the entire original string.
   Report whether more normalized content exists so fitting is not guessed.
2. Use standard `json.Marshal` on bounded normalized strings and rune-safe
   prefix selection with byte-budget accounting. Keep HTML/control escaping and
   valid UTF-8 JSON. Do not build a general custom JSON escaper.
3. Retain only bounded candidate buffers; scanning a long invalid-byte run may
   still be needed to preserve normalization. Do not invent a raw input limit
   or promise constant CPU regardless of input.

**Validation/outcome:** Focused helper behavior covers plain/escaped Unicode,
invalid-byte runs, empty/small budgets, and truncation boundaries. Wiring into
the public repair workflow follows in Stage 19; no interim alternative formatter
is exposed or new contract created for a helper's exact allocation count.

## Stage 19: Construct Repair Feedback Without Whole-Input Serialization

**Catalog:** 17, completion. **Files:** `formatRepairDiagnostics` and repair tests.

1. Attempt construction of the complete-list result within the existing 64 KiB
   budget, processing only useful bounded prefixes. Preserve the complete-list
   form when it fits, including existing empty/nil-list behavior.
2. If it cannot fit, build the omission form using the existing marker, ordering,
   separator/reservation rules, and bounded prefix helpers from Stage 18. Do not
   marshal the entire error list or an unbounded entry before deciding to truncate.
3. Leave full validation diagnostics and previous candidate stored as before;
   only the feedback representation is bounded. Preserve original repair-message
   ordering, attempts, provider-native structured output, and generation policy.

**Validation/outcome:** Cover fitting/exact-boundary, oversized single entry,
many entries, heavily escaped and invalid strings, valid JSON, and omission
semantics. Repeat the roadmap's three formatter workloads and record real
allocation results; aggregate allocation is not a peak-heap guarantee.

## Stage 20: Select Namespace Ranges Before Copying Inventories

**Catalog:** 20. **Files:** configuration/engine inventory interfaces and listing tests.

1. Resolve filters/view scope in the engine first, then pass private
   `configuration.IdentityFilter{All bool, Namespace string}` to the inventory.
   All true selects all IDs; false plus empty namespace selects unqualified IDs;
   false plus a name selects that exact namespace.
2. In captured sorted IDs, find a named prefix's start/end by binary search and
   copy only that contiguous range. For All, copy once; for unqualified IDs,
   scan immutable state directly and append matches without a prior whole copy.
3. Apply the same policy to profiles, backends, and prompt identities; migrate
   private fakes. Preserve caller-owned results, lexical order, context checks,
   empty success, namespace defaults, and explicit-filter precedence.

**Validation/outcome:** Test prefix-sharing namespaces, interleaved unqualified
IDs, All/default/views, missing matches, mutation, and cancellation. Repeat the
baseline through the new select-before-copy path. No persistent buckets/cache,
new public signature, or unqualified-query complexity promise is required.

## Stage 21: Put Authentication Protocol Mechanics In The Outbound Adapter

**Catalog:** 26. **Files:** llm authentication adapter, selection, assembly and tests.

1. Add an internal llm OpenRouter-key operation taking context, resolved endpoint,
   timeout/settings, and returning HTTP evidence, optional acceptance,
   overflow/unrecognized indicators, and operational error. It owns authenticated
   GET, bounded body consumption/closure, and account-response recognition.
2. Move default `/key` endpoint derivation to an llm helper used by selection;
   keep configured overrides and userinfo sanitization behavior. It is a focused
   provider adapter, not a plugin registry or dependency on use-case types.
3. Supply this operation from normal engine assembly through a narrow
   authentication capability alongside reachability HTTP capability. Update
   relevant test doubles without expanding public injection APIs.

**Validation/outcome:** Adapter tests use controlled HTTP for recognized/unknown
200, 401, other statuses, overflow, interruption, anonymous credentials, default/
override endpoints, and privacy. Stage 7's bound remains in the actual path;
Stage 22 finishes use-case cleanup and report projection.

## Stage 22: Narrow Diagnostic Orchestration And Copies

**Catalog:** 26, 27, completion.

1. Route authentication orchestration through Stage 21's capability and remove
   the use-case parser/body-consumption/default-protocol code. Keep support,
   applicability, selection, completion, context and reason/failure mapping in
   use cases. Preserve independently known HTTP/acceptance facts.
2. Replace `smokeReportTarget`'s empty-full-report clone with direct target
   detachment and existing JSON-value provider-map ownership/error handling.
   Retire unused request/full-report cloners and clone-specific helpers/tests
   only after checking their callers.
3. Keep facade request/report projection and real backend metadata cloning. Do
   not add an internal clone followed by another whole-report projection copy.

**Validation/outcome:** Focused smoke/adapter/facade ownership tests establish
unchanged tri-state facts, neutral outcomes, no ordinary observer events, target
redaction, and independent provider maps. Update owning internal documentation.

## Stage 23: Extract Final-Configuration Record Validators

**Catalog:** 22, validation part. **Files:** configuration validation and tests.

1. Keep `validateEffective`'s resource/index traversal visible; extract coherent
   backend/profile/prompt record checks with explicit record, path, and required
   index arguments. Keep capacity arithmetic, reference validation, and domain
   validation in their appropriate record operations.
2. Preserve final-handoff-only enforcement, recorded field presence/nulls,
   normalization, source context, and meaningful error identities. Do not inspect
   overwritten sources/history or create another resolution/validation phase.
3. Do not pin incidental ordering of independent validation failures or introduce
   reflection-driven field descriptors merely to reduce function size.

**Validation/outcome:** Existing configuration validation/inspection cases and
focused changed-seam cases retain final values, paths and relevant error meaning.
This stage changes organization, not configuration acceptance policy.

## Stage 24: Separate Prompt Capture And Effective Target Construction

**Catalog:** 22, completion. **Files:** configuration prompts/targets and tests.

1. Extract prompt input/metadata projection, message content/template capture,
   and output-contract conversion into focused operations returning the values
   needed by materialization. Retain lazy origin lookup and source-relative
   `content_file` access, then one final definition/inspection/hash assembly.
2. Extract coherent backend/profile target construction as useful, keeping
   presence interpretation together and explicit. Preserve fieldAbsent/null/
   value distinctions and Stage 14's selected overlay ownership.
3. Preserve fail-fast resource errors where meaningful; do not force every
   materialization check into the previous validation stage or aggregate errors
   that were previously operational/fail-fast.

**Validation/outcome:** Configuration capture, inheritance, origins, templates,
input metadata, inspection, and execution-selection tests keep their behavior.
Update focused source/internal descriptions without duplicating format policy.

## Stage 25: Replace Parallel Attempt Returns With A Result Value

**Catalog:** 25, attempt boundary. **Files:** generation coordinator and tests.

1. Define private `attemptResult` containing `Outcome llm.AttemptOutcome`,
   `Dispatched bool`, `CapacityWait`, `RequestDuration`, and `StartedAt`.
   Return it from built-in attempt execution instead of five parallel values.
2. Migrate consumers without changing acquire/dispatch/context transitions,
   response retention before cancellation, start timestamps, duration meanings,
   or evidence capture. Keep permit release deferred inside the attempt scope.
3. Leave retry eligibility/budgets/waits and injected dispatch strategy explicit.
   Stage 6's preparation failure remains outside attempt accounting.

**Validation/outcome:** Focused generation tests retain actual permit lifetime,
response/error behavior, timing facts and cancellation; no new event or HTTP fact
is fabricated for an injected client.

## Stage 26: Share Generation Accounting Projections

**Catalog:** 25, completion. **Files:** generation accounting/evidence/observer tests.

1. Extract common usage accumulation and evidence/event projection operations
   around the result boundary. Keep distinct built-in and injected paths where
   dispatch, HTTP evidence, or usage-presence compatibility actually differ.
2. Keep the retry loop about eligibility, budget, delay and terminal outcomes;
   preserve known/unknown/complete usage, private evidence and generation numbers.
3. Ensure permits release before observers and backoff, including panic unwinding.
   Do not add another permit layer, retry framework, transport retry, or helper
   that invokes observers while the attempt still holds capacity.

**Validation/outcome:** Existing observation, retry, diagnostic evidence,
injected usage compatibility and panic/cancellation cases exercise the real
coordinator. Expectations remain independent of the extracted projection helpers.

## Stage 27: Cover Request Privacy And Correct Public Documentation

**Catalog:** 11, 12, 13, 14. **Scope:** focused tests/comments, not new behavior.

1. Add marker-based RunRequest privacy formatting tests for values/pointers,
   `%v`, `%+v`, `%#v`, String/GoString and direct-key JSON omission. Put markers
   in omitted variables/bodies/settings, not IDs intentionally in summaries.
2. Correct credential-inspection GoDoc/example, recursive configured-map versus
   runtime-replacement wire prose, and stale trimmed-ID/prompt-Version comments.
   Link canonical format policy; do not change current behavior to fit old prose.

**Validation/outcome:** Focused formatting/JSON tests protect the actual privacy
boundary, and changed documentation links and semantics agree with canonical
GoDoc/formats. Do not snapshot whole diagnostic strings or unrelated JSON fields.

## Stage 28: Give Bundled Catalog Expectations One Test Owner

**Catalog:** 28. **Scope:** catalog tests, not bundled asset changes.

1. Keep the complete bundled inventory/model/plugin/default oracle in
   `internal/configuration/bundled_test.go`, with structural plugin assertions.
   Public option tests own toggles/order/isolation/overrides. Retain small
   controlled model/plugin wire and configured-default smoke tests instead of
   duplicated complete catalog matrices. Do not derive expectations from loading.
2. Remove duplicated full inventories and model/default matrices from other
   layers while preserving their distinct public option, routing, serialization,
   and diagnostic-selection assertions. Keep independent expected asset values
   in the owning test rather than deriving them from the loader under test.

**Validation/outcome:** Focused internal bundle and public option/wire/smoke tests
retain assembled behavior with a single complete maintained-asset oracle.

## Stage 29: Test Artifact Hashes As Opaque Values

**Catalog:** 29. **Scope:** artifact tests and benchmark correctness setup.

1. Replace literal SHA artifact assertions with same-body inline/file equality
   and actual bytes/size checks. Prepare an opaque expected hash outside benchmark
   timing; retain meaningful parity/read-boundary coverage.
2. Remove obsolete algorithm-specific test imports/calculations. Do not change
   the production artifact hash or delete the cases that catch hashing only a
   misreported-size prefix instead of the complete body.

**Validation/outcome:** Artifact parity, size-hint and read-boundary cases remain
meaningful without choosing an opaque value's algorithm. Keep benchmark setup
outside timed work and do not add a new encoding guarantee.

## Stage 30: Remove Unconsumed State And Orphan Helpers

**Catalog:** 30, remaining half of 32, 33.

1. Remove backend-only presence capture/map/field list and runtime
   `QueueCapacitySet` bookkeeping. Keep profile/input field-state consumers,
   effective queue values/defaults/explicit zero and ConfigKit provenance.
2. Remove the private reachability outcome endpoint echo; keep the real public
   attempt endpoint and sanitization evidence. The discarded `fileSource`
   directory result was removed in Stage 13; verify no callers were missed.
3. Remove internal `filecatalog.RelativePath`, `resourceNamespaceFromID`, their
   now-irrelevant self-tests, and unused runner-test `stringPtr`. Confirm caller
   searches against the current tree; do not broaden this into a deletion sweep.

**Validation/outcome:** Focused queue/provenance, reachability/privacy, file
discovery and identity/listing behavior remain covered. Optional public helpers,
capability fallbacks, and embedded/release assets are not deletion candidates.

## Stage 31: Remove Redundant Captured Prompt Fields

**Catalog:** 31. **Files:** domain prompt values, configuration capture, runner/fixtures.

1. Remove duplicate runtime `PromptDefinition.OutputFormat` and the runner
   fallback to it; validated `Validation.Format` is the captured source of truth.
2. Remove runtime `PromptMessageTemplate.ContentFile` only. Preserve the actual
   configuration `content_file` field, source-relative loading, origins, and
   already-captured message content/templates. Adjust fixtures accordingly.
3. Keep request replacement-contract empty Format defaulting to text. A fixture
   constructing a malformed internal definition does not justify a production
   compatibility fallback outside supported construction.
4. Account for changed marshaled definition hashes: preserve opaque equality
   relationships between inspection/preparation and note cache/comparison impact
   in migration guidance, without freezing old encodings or changing artifact hashes.

**Validation/outcome:** Prompt capture/rendering, public inspection/preparation,
output overrides and hash-relation tests pass with independently specified
behavior. No assertion of bit-identical previous hash values is added.

## Stage 32: Retire The Legacy Production Capacity Wrapper

**Catalog:** 34. **Files:** runner scheduling test, capacity wrapper/tests/docs.

1. Use `generation.NewInjected` with the same manager in the initial/repair
   scheduling test so it exercises actual engine composition and shared limits.
2. Migrate useful capacity wrapper scenarios to direct manager tests or small
   test-only one-shot scaffolding. Preserve FIFO, peak concurrency, canceled
   waiter/grant races, independent/unlimited pools and panic release.
3. Delete production `internal/capacity/client.go` after callers migrate and
   remove its retention prose. Keep the manager and coordinator's distinct owners;
   never wrap the coordinator in a second acquisition layer.

**Validation/outcome:** Race-enabled focused capacity/generation/use-case tests
exercise the real scheduling path. No production scheduling policy or public
API changes; no-repair runner construction and other deliberate fallbacks remain.

## Stage 33: Reconcile Documentation And Validate The End State

**Catalog:** all entries; complete the sprint, not a release publication.

1. Reconcile owning GoDoc, consumer guidance, framework formats, wire integration,
   contributor guidance and focused internal documents with the final code.
   Describe the artifact handoff, supported source forms, self-contained schemas,
   explicit overflow reason and deliberate hash changes where consumers need them.
   Remove obsolete external-loader/wrapper/current-behavior descriptions.
2. Record the migration summary and actual completion/evidence in the roadmap
   for subsequent minor-release preparation. Do not select/tag/push a release,
   change historical notes, or impose publication/network checks in this sprint.
3. Check the coverage table below against actual edits and test results. Do not
   mark an optimization complete without its comparable post-change evidence, or
   a behavior fixed solely because another refactor landed nearby. Name remaining
   work accurately if new evidence prevents completion; do not silently defer it.
4. Format changed Go files and run the complete offline final checks with the
   selected toolchain: `go test -race ./...`, `go vet ./...`, and
   `git diff --check`. The default Go suite includes maintained examples; do not
   run a duplicate standalone build/example/full non-race suite as another gate.
   Check changed local Markdown targets/anchors and repository hygiene. Reuse
   focused evidence for unchanged code; rerun affected checks after corrections.

**Final outcome:** The repository compiles coherently, the selected remediations
and compatibility guidance are implemented, meaningful tests remain independent,
post-change measurements are recorded without new performance guarantees, and
no unapproved feature/policy/dependency changes or temporary harnesses are left
in the repository. Follow normal commit policy; release preparation remains separate.

## Catalog Coverage

| Catalog finding | Owning stages |
| --- | --- |
| 1 | 1 |
| 2 | 7 |
| 3, 5 | 2 |
| 4 | 8 |
| 6 | 11–13 |
| 7 | 3–4 |
| 8 | 5 |
| 9 | 6 |
| 10 | 16 |
| 11–14 | 27 |
| 15 | 13 |
| 16, 18 | 9 |
| 17 | 18–19 |
| 19 | 14 |
| 20 | 20 |
| 21 | 10–13 |
| 22 | 23–24 |
| 23 | 17 |
| 24 | 15 |
| 25 | 25–26 |
| 26 | 21–22 |
| 27 | 22 |
| 28 | 28 |
| 29 | 29 |
| 30 | 30 |
| 31 | 31 |
| 32 | 13, 30 |
| 33 | 30 |
| 34 | 32 |

Stage 33 verifies the combined end state. No significant product questions
remain open; equivalent private implementation details remain flexible within
the selected designs and preservation requirements.