From fb6cb49ba65575c8ea54a83a5d8e88d14b09a74d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 15 Nov 2026 17:12:34 +0000 Subject: [PATCH] Record dead code and obsolete functionality audit findings --- docs/roadmap/audit/12-deadcode.md | 263 ++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/roadmap/audit/12-deadcode.md diff --git a/docs/roadmap/audit/12-deadcode.md b/docs/roadmap/audit/12-deadcode.md new file mode 100644 index 0000000..490b25d --- /dev/null +++ b/docs/roadmap/audit/12-deadcode.md @@ -0,0 +1,263 @@ +# Dead code and obsolete functionality audit + +Reviewed at `9110aed`. Audita is a single-process Go CLI. CommandKit dispatches +the command and inspection surfaces. The application loads version 3 settings, +parses and normalizes the transcript, and passes it to a runner that chunks it +and coordinates proposals, validation, repair, and application. The PromptKit +adapter performs model calls. The CLI publishes the selected transcript format +and reports, with separate opt-in debug evidence. +[Package map](../../internal/overview.md) · [Pipeline](../../internal/pipeline.md) + +## Scope and verification + +The review used Go's `deadcode` analyzer from `x/tools` v0.52.0 on `./...`, +with and without test entry points, and Staticcheck 2026.2.2 for unused +declarations and ineffectual operations. Production reachability returned the +same 19 candidates for both shipped Linux targets, amd64 and arm64. The native +test-inclusive scan returned 16 candidates, including test-only declarations. +Typed reference counts helped locate write-only fields. The review traced +whole-value serialization, command registration, embedded assets, interface +assertions, and build selection before selecting findings. The FIFO test's +Linux and Darwin build constraint is intentional. `go vet -unreachable ./...` +produced no diagnostics, and `go test -count=1 ./...` passed on Go 1.27.3. +[Release targets](../../../releasekit.json#L7) · [Platform test](../../../internal/core/diagnostics/output_stream_test.go#L1) + +## 1. Retire the test-only direct continuation path + +`structuredoutput.Request.ContinueFrom` is read in `RoleClient.prepareCall`, +where it has its own opaque exchange check and passes the exchange to an +ordinary `Engine.Run`. The only request literals that set it are in +`conversation_test.go`. The supported correction-repair path passes the +captured proposal exchange to `Coordinator.Coordinate`. Its callback builds +requests without `ContinueFrom`, and the PromptKit coordinator supplies +history and owns the turn budget. A function-level scan sees the shared +request preparer as live, even though its continuation branch has no +production caller. [Request fields](../../../internal/framework/structuredoutput/call.go#L26) · +[Direct continuation](../../../internal/framework/llm/adapter.go#L127) · +[Direct callers in tests](../../../internal/framework/llm/conversation_test.go#L73) · +[Runner repair](../../../internal/framework/runner/repair.go#L143) · +[Coordinator adapter](../../../internal/framework/llm/coordinate.go#L13) + +Move meaningful coverage of sibling isolation, carried context, and structural +repair onto coordinated calls, then remove the request field and direct +continuation branch. Keep exchange capture for proposals and keep the live +coordinator's cancellation, final-turn, and accounting checks. +[Second continuation fixture](../../../internal/framework/llm/conversation_test.go#L113) · +[Coordinator tests](../../../internal/framework/llm/coordinate_test.go#L15) · +[Subprocess repair test](../../../cmd/audita/correction_repair_integration_test.go#L173) + +## 2. Remove proposal enrichment that the live handoff discards + +`GenerateCandidates` appends both a plain proposal and an enriched proposal for +each decoded correction. The only production wrapper, `ExecuteModuleProposal`, +passes `StartIndex: 0` and forwards the plain proposals, segment references, +exchange, and operations. The runner creates its own enriched proposals and +assigns indices in ordered section collection. Only tests consume generation's +`Result.Enriched` or supply a nonzero `StartIndex`. Those tests can still pass +when the runner assigns incorrect run-level indices. +[Duplicate construction](../../../internal/framework/proposal_generation/generate.go#L189) · +[Production wrapper](../../../internal/framework/proposal_generation/module_proposal.go#L55) · +[Runner assignment](../../../internal/framework/runner/runner.go#L522) · +[Generator index assertions](../../../internal/framework/proposal_generation/generate_test.go#L238) + +Return one proposal representation from generation and use the runner tests +for global ordering. The adapter integration fixture can prepare validation +input explicitly or exercise the runner handoff. Review the debug metadata +before dropping `StartIndex`, since its `start_index` field is emitted with a +constant zero through the current module path. Keep the actual local segment +references and operation facts. +[Adapter fixture](../../../internal/framework/proposal_generation/adapter_integration_test.go#L76) · +[Runtime ordering test](../../../internal/framework/runner/runner_test.go#L423) · +[Debug metadata field](../../../internal/framework/proposal_generation/generate.go#L148) + +## 3. Remove duplicate runner bookkeeping for unused module totals + +`runModulePipeline` increments a module proposal count and flattens work-unit +operations into a second slice. `Run` copies that count into each `ModuleResult`. +It uses the flattened operations on failures and, on success, flattens the +enriched work-unit operations again after apply-time attribution. No current +consumer reads `ModuleResult.ProposalCount`. Only tests read +`ModuleResult.Operations`. Ordinary reports consume `RunOutput.WorkUnits`, +and the correction ledger uses the module's decisions and applied and skipped +changes. The CLI serializes those projections, so the JSON tags on the unused +module fields never turn them into output fields. +[Count accumulation](../../../internal/framework/runner/runner.go#L536) · +[First operation copy](../../../internal/framework/runner/runner.go#L620) · +[Second operation copy](../../../internal/framework/runner/runner.go#L264) · +[Report work-unit input](../../../internal/framework/processreport/report.go#L51) · +[CLI artifact projections](../../../internal/cli/process_pipeline.go#L56) + +Remove the unused count and the module-level copies once the partial-failure +and accounting tests assert the corresponding work units. Retain the +per-module status and edit evidence consumed by reporting and the ledger. +[Ledger input](../../../internal/framework/processreport/correction_ledger.go#L70) · +[Partial-progress tests](../../../internal/framework/runner/runner_test.go#L685) + +## 4. Drop the unconsumed validation request envelope + +`BuildLLMValidationRequest` constructs a `LLMValidationRequest` holding the +validator name, type, module key, module instance, replacement policy, and a +slice of items. The caller takes only `.Items`. Batch encoding serializes +local-reference items, and diagnostics source their labels directly from the +validator and runtime request. The envelope is never passed to JSON encoding. +Each item also stores `SegmentID`, which is assigned after the segment lookup, +never read, and explicitly excluded from JSON. The result's duplicate +`ValidatorName` likewise has no production reader. The runner reads the +validator's `Name()` when recording decisions. +[Envelope construction](../../../internal/framework/validators/llm_validators.go#L242) · +[Runtime consumer](../../../internal/framework/validators/llm_validators.go#L61) · +[Fields and wire exclusions](../../../internal/framework/validators/llm_models.go#L20) · +[Payload construction](../../../internal/framework/validators/llm_prompt_variables.go) · +[Decision recorder](../../../internal/framework/runner/runner.go#L775) + +Have the builder return items and immediate decisions. Remove the write-only +fields after checking fixtures. Keep proposal indices for reconciliation and +the active diagnostic labels. The unused duplicate `framework/validators.Validator` +interface can also go. The module and runner use `contracts.Validator`. +[Unused interface](../../../internal/framework/validators/models.go#L95) · +[Active interface](../../../internal/framework/contracts/contracts.go#L29) · +[Payload parity test](../../../internal/framework/validators/llm_budget_test.go#L17) + +## 5. Remove structured-call fields superseded by execution observations + +The adapter still sets `Response.Provider` to a fixed string and copies prompt, +completion, and total token counts out of the run result. No production consumer +reads those response fields or serializes the whole response. The debug +execution projection gets usage from terminal events and the execution group. +`CallRecord.Prepared` and `CallRecord.FinalContent` are also populated even +though the observation collector copies only the call metadata. Interaction +artifacts get those payloads from `Response`, and a test currently asserts the +duplicated final content on the callback record. +[Response model](../../../internal/framework/structuredoutput/call.go#L52) · +[Adapter assignments](../../../internal/framework/llm/adapter.go#L153) · +[Collector projection](../../../internal/framework/llm/observations.go#L126) · +[Debug execution rendering](../../../internal/framework/processreport/llm.go#L61) · +[Test-only response and callback assertions](../../../internal/framework/llm/adapter_test.go#L167) + +Remove the unconsumed response summaries and callback payload copies. Move +tests to the native usage observation and actual interaction payload paths. +Preserve `Response.Execution` for ordinary report counts and retain prepared +and final response evidence in the opt-in interaction artifacts. +[Observation mapping](../../../internal/framework/llm/observations.go#L139) · +[Interaction payload](../../../internal/framework/proposal_generation/generate.go#L159) + +`Failure.Kind` is a related, explicitly transitional field. The adapter sets +it in tandem with `ReasonInvalidOutputExhausted` and production uses the reason +and class. The remaining reads are from `IsMalformedError` in tests. The debug +call record independently derives its `failure` value from the reason. Move +the tests to the typed reason and remove the compatibility field and helper. +Keep the diagnostic `FailureKind` values, the safe failure message, and the +wrapped cause. [Transitional field and helper](../../../internal/framework/structuredoutput/failure.go#L17) · +[Paired assignments](../../../internal/framework/llm/adapter.go#L279) · +[Debug failure mapping](../../../internal/framework/llm/adapter.go#L86) · +[Cause and classification tests](../../../internal/framework/structuredoutput/failure_test.go#L10) + +## 6. Resolve shared prompt variables once per model call + +`prepareCall` invokes `WithSharedVariables`, which loads all four embedded +instruction values and fills missing keys. The following loop reloads those +same assets and overwrites every one of those keys. For processing calls, +the first pass over shared instruction values is redundant. The helper is +still useful in CLI request inspection, where caller values take precedence. +[Processing merge](../../../internal/framework/llm/adapter.go#L123) · +[Shared values and merge semantics](../../../internal/prompts/registry.go#L82) · +[Inspection caller](../../../internal/cli/app_wiring.go#L100) + +Use a single merge in the processing path that preserves the embedded-values +precedence and the missing `ProtectedTermsJSON` default. Keep the inspection +merge semantics and retain the existing prompt rendering coverage. +[Operator prompt test](../../../internal/framework/llm/adapter_test.go#L291) + +## 7. Remove orphaned normalization and file helpers + +The analyzer and repository references agree that `normalization.shouldMerge`, +`core/io.ValidateWellFormedJSON`, and `core/io.WriteFile` are unreachable in +production and tests. The normalizer calls `shouldMergeWithReason` so it can +count skipped merge reasons. The CLI reads the transcript and calls the schema +parser, which already validates JSON. Current output delivery goes through +`OutputSession` and has a different lifecycle from `os.WriteFile`. +[Unused merge predicate](../../../internal/core/normalization/normalize.go#L115) · +[Live merge caller](../../../internal/core/normalization/normalize.go#L73) · +[File helpers](../../../internal/core/io/files.go#L17) · +[Live input boundary](../../../internal/cli/process_inputs.go#L46) · +[Live delivery boundary](../../../internal/core/diagnostics/output_session.go#L273) + +Delete the three declarations and retain the live merge checks, labeled input +read, and publication paths. Existing normalization and output tests cover +the behavior these helpers formerly duplicated or bypassed. +[Normalization limit test](../../../internal/core/normalization/normalize_test.go#L155) · +[Publication tests](../../../internal/core/diagnostics/output_session_test.go#L207) + +## 8. Remove the transcript parser variants that only tests call + +The CLI calls `ParseSourceTranscriptJSON`, keeps the source for debug, then +converts it to the processing model before normalization. Neither +`ParseTranscriptJSON` nor `ParseTranscriptJSONLenient` is reached from the CLI. +The strict wrapper and its sequential-ID helper are used by schema tests. The +strict wrapper dereferences source IDs even though source input allows them to +be omitted. The lenient wrapper duplicates the live conversion and has a +test-only caller. Neither wrapper is an external Go API because the package is +internal. [Live load](../../../internal/cli/process_inputs.go#L46) · +[Live conversion](../../../internal/cli/run.go#L12) · +[Strict and lenient variants](../../../internal/core/schema/transcript.go#L65) · +[Parser and round-trip tests](../../../internal/core/schema/transcript_test.go#L166) + +Move the live conversion to the schema package if a shared seam is useful. +Use the supported source decoder and explicit field expectations to test +serialized transcripts, and exercise missing-ID conversion through the live +entry point. That leaves the optional source IDs, normalization's sequential +output, and both output formats intact. [Transcript input contract](../../integrations/transcript-glossary-files.md#transcript-json-contract) · +[Boundary finding](11-boundaries.md#9-put-transcript-conversion-and-output-shape-at-their-owning-boundaries) + +## 9. Clean up abandoned test support + +`internal/testsupport` has no imports from Go code anywhere in the repository, +including tests. All four filesystem and redaction helpers are flagged by both +reachability runs. Staticcheck also reports the old subprocess configuration +view helper, the runner entry wait helper, and two runner structured-client +fixtures with no callers. Current configuration and redaction tests run with +their own fixtures. The unused test doubles differ from the explicit interface +conformance fixtures in `contracts_test.go`, whose methods exist to satisfy +compile-time type assertions. +[Orphan helper package](../../../internal/testsupport/files.go) · +[Unused config view helper](../../../cmd/audita/main_integration_test.go#L319) · +[Unused wait helper](../../../internal/framework/runner/runner_test.go#L503) · +[Unused test clients](../../../internal/framework/runner/runner_test.go#L615) · +[Compile-time fixture](../../../internal/framework/contracts/contracts_test.go#L64) + +Delete the orphan package and unused fixtures. Keep the active assertions in +the configuration inspection, artifact, and runner suites. + +## 10. Resolve the inherited progress flag for `process` + +The built executable advertises `audita process --progress` as showing +progress messages. The process command registers no progress producer. The +pipeline attaches model observations only for debug capture, and the CLI's +processing summary and path messages are emitted at completion. In a local +normalization-only invocation, `--progress` and the default invocation returned +identical transcript bytes and empty stderr. The source trace is the evidence +for the model path too, since its observation hook is connected to the debug +artifact and no process progress callback is supplied. +[Command registration](../../../internal/cli/app_wiring.go#L84) · +[Processing observation wiring](../../../internal/cli/process_pipeline.go#L20) · +[Completion reporting](../../../internal/cli/process_output.go#L61) + +Treat this as an exposed option with no Audita process behavior. Either attach +it to a real process event source or clarify its availability in process help +while retaining acceptance for existing scripts. The delegated inspection and +smoke commands have their own reporting behavior. + +## Retained behavior + +The version gate rejects older explicit configuration versions. The flags +marked for removal in the migration guide are absent from command help and +registration. `chunking.min_section_tokens` is documented, accepted and +validated, and the chunker explicitly +retains it for compatibility even though partitioning does not use it as a +target. Keep that setting. Also keep the generic validator estimator path, +which supplies the independent serialized reference in the existing budget +comparison, and the debug-only metadata reached through serialization. +[Migration guide](../../migrations/v3.md) · +[Version gate](../../../internal/core/config/config.go#L131) · +[Chunk compatibility field](../../../internal/core/chunking/sections.go#L27) · +[Budget reference test](../../../internal/framework/validators/llm_budget_test.go#L14)