diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md new file mode 100644 index 0000000..480ce49 --- /dev/null +++ b/docs/roadmap/audit/catalog.md @@ -0,0 +1,520 @@ +# Consolidated audit catalog + +Audita is a single-process Go CLI. CommandKit dispatches commands and ConfigKit +resolves application settings. Core packages parse, normalize, and chunk +transcripts. The runner coordinates proposals, validation, repair, and application +through a PromptKit adapter. The CLI publishes the corrected transcript and +ordinary reports, with separate opt-in debug artifacts. +[Package map](../../internal/overview.md) · [Pipeline](../../internal/pipeline.md) + +The 11 source audits contain 103 numbered findings. This catalog consolidates them +into 62 entries. Priority reflects potential impact, exposure, and the strength of +the reported evidence. A source can appear under several entries when it covers +distinct issues. Each link leads to the original finding and its supporting +evidence. + +## Data protection and run integrity + +### 1. Bind output writes to the checked destinations + +Transcript path resolution can select the wrong target, and report writers can +change referents after preflight. Use filesystem-consistent resolution and carry +the checked destination into publication. Cover changed report referents as well +as initially ambiguous paths. +[Correctness §1](01-correctness.md#1-output-path-resolution-can-replace-a-different-file) · +[Concurrency §6](04-concurrency.md#6-report-paths-can-change-referent-between-initialization-and-finalization) · +[Security §3](07-security.md#3-report-destinations-can-escape-the-identity-checked-by-preflight) · +[Testing §3](08-testing.md#3-output-tests-primarily-check-the-final-artifact-state) · +[Complexity §9](03-complexity.md#9-clarify-output-preparation-publication-and-failure-ownership) + +### 2. Keep model requests within the configured transport boundary + +Provider redirects can take transcript-bearing requests outside the selected +origin or downgrade the transport. Define redirect and credential forwarding rules +for the model client, including explicitly trusted destinations. +[Security §2](07-security.md#2-provider-redirects-can-cross-the-configured-transport-boundary) + +### 3. Protect credentials inside nested debug responses + +Outer artifact redaction can leave credentials in a nested structured response. +Verify the decoded content of retained artifacts and define safe retention for +content that cannot be decoded. +[Security §4](07-security.md#4-raw-structured-debug-responses-can-retain-an-encoded-credential) · +[Testing §8](08-testing.md#8-debug-redaction-assertions-mostly-inspect-the-outer-serialization) + +### 4. Make debug artifact permissions private by default + +Opt-in debug capture can expose transcript and model artifacts under a shared +parent. Use a per-user default and private creation modes, and document the trust +assumptions for explicitly shared destinations. +[Security §1](07-security.md#1-debug-capture-uses-a-shared-path-and-can-expose-private-artifacts) + +### 5. Define the trust boundary for discovered configuration + +The selected main file and its automatic companions can influence provider and +credential selection. Document trusted configuration locations and keep +upload-controlled paths separate from operator configuration. +[Security §5](07-security.md#5-configuration-discovery-extends-trust-to-the-main-file-and-its-neighbors) + +### 6. Make blocking transcript input and delivery cancellation-aware + +Input can block before preflight. FIFO or stdout delivery can hold resources past +cancellation and later produce a success status. Verify interrupted reads and +writes at the subprocess boundary and finalize reports as failed when delivery is +canceled. +[Correctness §5](01-correctness.md#5-cancellation-during-fifo-delivery-can-hang-and-later-report-success) · +[Concurrency §1](04-concurrency.md#1-blocked-output-delivery-can-ignore-cancellation-and-report-success) · +[Concurrency §2](04-concurrency.md#2-waiting-for-transcript-input-can-prevent-shutdown-before-preflight) · +[Resources §2](05-resources.md#2-blocked-stream-io-extends-resource-lifetime-past-cancellation) · +[Security §7](07-security.md#7-untrusted-input-size-and-blocking-io-can-exhaust-subprocess-workers) · +[Testing §3](08-testing.md#3-output-tests-primarily-check-the-final-artifact-state) + +### 7. Publish truthful failure reports and preserve initialized evidence + +A delivery failure can briefly publish `completed` reports. The internal preflight +seam can also replace initialized reports with empty files when failed-report +rendering is unavailable. Verify the first published state and preserve valid +existing evidence if a failed bundle cannot be rendered. +[Error handling §1](06-error-handling.md#1-finalization-publishes-completed-reports-after-it-knows-delivery-failed) · +[Complexity §13](03-complexity.md#13-missing-failed-report-rendering-can-erase-initialized-evidence) · +[Testing §3](08-testing.md#3-output-tests-primarily-check-the-final-artifact-state) + +### 8. Prevent concurrent runs from clobbering ordinary reports + +Invocations sharing a report directory replace the same basenames and can leave a +mixed set. Document destination isolation for callers and define publication +ownership if shared destinations are supported. +[Concurrency §7](04-concurrency.md#7-concurrent-invocations-sharing-a-report-directory-replace-each-others-evidence) + +### 9. Preserve the ordinary YAML schema during redaction + +A credential value can match a required key or fixed enum and alter an otherwise +successful report. Redact data-bearing fields while preserving required keys and +values. +[Correctness §9](01-correctness.md#9-credential-redaction-can-change-the-ordinary-yaml-schema) + +### 10. Reject contradictory validation decisions + +The internal decision boundary can advance a candidate marked both approved and +unavailable. Validate the disposition and approval invariant before filtering or +repair. The bundled validators produce consistent decisions in the audited paths. +[Complexity §11](03-complexity.md#11-a-contradictory-validator-decision-can-advance-an-unavailable-candidate) + +### 11. Preserve usable validator decisions when extra references cannot be decoded + +A schema-valid unexpected numeric reference can fail whole-batch Go decoding +before per-entry reconciliation. Preserve valid requested siblings and test the +mixed response at the actual adapter boundary. +[Correctness §7](01-correctness.md#7-an-extra-numeric-validator-reference-can-discard-valid-sibling-decisions) · +[Testing §5](08-testing.md#5-the-validator-batch-fixture-misses-the-real-numeric-decoding-boundary) + +### 12. Use full-segment evidence for protected-name checks + +Span-only validation can reject a valid edit or miss a repair opportunity. Share a +glossary-owned matching and protection assessment across validation and +application, and recheck the current segment when applying an edit. +[Correctness §8](01-correctness.md#8-span-only-protection-can-reject-a-valid-edit-or-miss-a-repair-opportunity) · +[Equivalence §9](10-equivalence.md#9-reconcile-the-protection-rule-at-validation-and-application) · +[Boundaries §5](11-boundaries.md#5-give-glossary-matching-and-protection-a-domain-owner) + +### 13. Preserve transcript input fidelity during JSON shape detection + +Generic decoding can round large integer IDs and fail on values in fields the +typed reader ignores. Select the segment array as raw JSON and test exact IDs +across both supported input shapes. +[Correctness §6](01-correctness.md#6-transcript-shape-detection-loses-integer-and-unknown-field-fidelity) · +[Testing §7](08-testing.md#7-representative-transcript-fixtures-leave-data-integrity-boundaries-open) · +[Resources §4](05-resources.md#4-whole-transcript-copies-amplify-memory-at-input-and-publication) + +### 14. Honor cancellation at the runner commit boundary + +An already canceled empty pipeline can return success, and cancellation during +module application can still allow the runner to commit edits. Check entry and +final commit boundaries and give successful and interrupted results one assembly +path. +[Complexity §1](03-complexity.md#1-give-module-execution-one-place-to-commit-its-result) · +[Complexity §12](03-complexity.md#12-the-runner-accepts-an-already-canceled-empty-pipeline) · +[Concurrency §3](04-concurrency.md#3-cancellation-can-cross-the-runners-module-commit-boundary) + +### 15. Retain completed proposal evidence behind slow sections + +The ordered prefix gate can delay validation for ready sections and omit completed +proposal evidence on interruption. Capture usable responses independently of +validation dispatch and preserve deterministic identities. +[Correctness §10](01-correctness.md#10-a-completed-proposal-can-disappear-from-the-interruption-ledger) · +[Concurrency §4](04-concurrency.md#4-a-slow-earlier-proposal-holds-back-later-validation-and-retention) · +[Complexity §1](03-complexity.md#1-give-module-execution-one-place-to-commit-its-result) + +### 16. Keep ownership of failed staging cleanup + +Removal errors can discard temporary paths or go unreported, preventing a retry. +Keep paths until removal succeeds or the path is absent and verify cleanup +failures and cancellation after output acquisition. +[Resources §1](05-resources.md#1-failed-output-cleanup-loses-ownership-of-temporary-paths) · +[Testing §3](08-testing.md#3-output-tests-primarily-check-the-final-artifact-state) + +## Correctness and failure reporting + +### 17. Preserve the complete time interval when merging segments + +A nested segment can shorten the merged end time and change later gap and duration +decisions. Use the full interval for both eligibility and output, and cover nested +intervals in normalization tests. +[Correctness §3](01-correctness.md#3-merging-nested-segments-truncates-the-earlier-timestamp-range) · +[Testing §7](08-testing.md#7-representative-transcript-fixtures-leave-data-integrity-boundaries-open) + +### 18. Match protected names at Unicode and punctuation boundaries + +The matcher misses some names with accented letters or punctuation at their edges. +Define boundary semantics that work for both protection and context selection. +[Correctness §2](01-correctness.md#2-glossary-matching-misses-names-with-accented-letters-or-punctuation-at-their-edges) + +### 19. Detect overlapping occurrences when requiring a unique edit span + +Nonoverlapping counting can treat a repeated overlapping span as unique. Use one +literal occurrence rule in preview, validation, and application. +[Efficiency §7](02-efficiency.md#7-the-unique-span-check-accepts-overlapping-matches) + +### 20. Satisfy feasible explicit chunk targets + +A balancing preference can reject inputs that have a valid contiguous partition. +Make the configured count and limits prerequisites, then optimize balance within +feasible choices. Verify skewed inputs at the feasibility boundary. +[Correctness §4](01-correctness.md#4-balanced-chunking-rejects-feasible-explicit-targets) · +[Testing §7](08-testing.md#7-representative-transcript-fixtures-leave-data-integrity-boundaries-open) + +### 21. Keep input order for exactly tied timestamps + +An unstable sort can reorder utterances with identical times. Use source position +as a stable tie-breaker. +[Efficiency §8](02-efficiency.md#8-normalization-can-reorder-utterances-with-exactly-tied-timestamps) + +### 22. Preserve failure phase and origin in run reports + +Required output errors can omit their phase, and fatal model errors can lose +chunk, role, validator, or batch coordinates. Carry typed failure facts from their +source and assemble run records and counts in one place. Assert the serialized +fields. +[Correctness §11](01-correctness.md#11-required-delivery-failures-omit-the-phase-in-run-error-records) · +[Error handling §4](06-error-handling.md#4-fatal-model-errors-lose-their-chunk-and-operation-coordinates) · +[Testing §3](08-testing.md#3-output-tests-primarily-check-the-final-artifact-state) · +[Boundaries §8](11-boundaries.md#8-give-run-level-report-facts-one-assembly-path) · +[Complexity §9](03-complexity.md#9-clarify-output-preparation-publication-and-failure-ownership) + +### 23. Classify provider attempt timeouts separately from operation deadlines + +The adapter can report an HTTP attempt timeout as a logical operation deadline. +Use the native classifications and test attempt, operation, and parent +cancellation under distinct live budgets. +[Error handling §2](06-error-handling.md#2-a-provider-request-timeout-is-reported-as-the-logical-operation-deadline) · +[Testing §4](08-testing.md#4-the-timeout-tests-cover-two-of-the-three-relevant-deadline-owners) + +### 24. Use input diagnostics for operator-correctable failures + +Invalid processing selections and malformed inspection configuration can return +the runtime exit status. A genuinely infeasible chunk target can also be reported +as an internal defect. Preserve the distinction between readiness, chunking, and +runtime failures and assert exact statuses in CLI tests. In the inspection tests, +use a fixture that actually exercises redaction if asserting credential masking. +[Error handling §5](06-error-handling.md#5-invalid-processing-selections-use-the-runtime-failure-exit-status) · +[Error handling §6](06-error-handling.md#6-an-infeasible-chunk-target-is-recorded-as-an-internal-processing-failure) · +[Testing §2](08-testing.md#2-inspection-failure-tests-accept-the-wrong-exit-classification) + +### 25. Identify missing required credentials in safe diagnostics + +The process path reduces a known missing credential requirement to a generic setup +failure. Surface the configured requirement safely and preserve the underlying +typed cause. +[Error handling §3](06-error-handling.md#3-missing-required-credentials-produce-a-generic-setup-message) + +### 26. Render input and output paths as plain Markdown text + +Untrusted filenames can alter the rendered report or its navigation. Escape path +text consistently with other untrusted labels and verify the rendered meaning. +[Security §6](07-security.md#6-untrusted-transcript-filenames-can-become-active-markdown) + +### 27. Keep the validator execution class used by the runner + +The ledger can infer a different class from an injected validator's name. Carry +the resolved class in decision evidence and join the evidence once before emitting +rows, preserving disposition and repair lineage. +[Complexity §8](03-complexity.md#8-join-correction-evidence-before-building-ledger-rows) · +[Boundaries §2](11-boundaries.md#2-preserve-the-execution-class-assigned-to-each-validator-decision) + +### 28. Verify signal and exit handling in the production executable + +Subprocess fixtures recreate startup wiring and can miss regressions in the actual +binary. Exercise the built executable or share the production entry point for +representative startup and cancellation cases. +[Testing §1](08-testing.md#1-subprocess-tests-recreate-the-production-executable-boundary) + +### 29. Fail the release bootstrap when cleanliness cannot be established + +A failed Git status command can be mistaken for a clean checkout. Check its status +explicitly and exercise that boundary in place of testing the release test's own +comparison helper. The delivery tool has a separate prepared-checkout check. +[Error handling §7](06-error-handling.md#7-ci-bootstrap-treats-a-failed-git-status-command-as-clean-if-stdout-is-empty) · +[Testing §11](08-testing.md#11-remove-the-tests-of-the-release-tests-own-set-helper) + +## Scalability and resource use + +### 30. Bound pending proposal work before backend admission + +One goroutine per chunk makes finite-capacity rejection depend on scheduling and +can retain requests and results across the whole run. Bound dispatch and result +retention without changing the module barrier or backend admission ownership. +Verify actual contention and cancellation in tests. +[Concurrency §5](04-concurrency.md#5-proposal-fan-out-makes-admission-under-finite-capacity-depend-on-scheduling) · +[Resources §3](05-resources.md#3-backend-admission-leaves-chunk-fan-out-and-result-retention-unbounded) · +[Testing §6](08-testing.md#6-concurrency-fixtures-leave-some-schedules-unproved) + +### 31. Reduce peak memory for large transcript input and output + +Whole-file reads, a generic JSON tree, retained source bytes, and full output +buffers amplify memory before and after model work. Reduce live copies and +consider explicit limits for integrations handling uploads. +[Resources §4](05-resources.md#4-whole-transcript-copies-amplify-memory-at-input-and-publication) · +[Security §7](07-security.md#7-untrusted-input-size-and-blocking-io-can-exhaust-subprocess-workers) + +### 32. Retain only the run evidence required by enabled outputs + +Ordinary runs retain debug-only candidates and decision history. Summary-only runs +still allocate the full work-unit grid, and module results duplicate operation +records and unused proposal totals. Preserve live validation and repair state, and +collect compact counts when detailed evidence is disabled. +[Efficiency §5](02-efficiency.md#5-ordinary-runs-retain-debug-only-decision-history) · +[Resources §5](05-resources.md#5-summary-only-runs-retain-a-full-grid-of-work-and-operation-records) · +[Dead code §3](12-deadcode.md#3-remove-duplicate-runner-bookkeeping-for-unused-module-totals) + +### 33. Limit debug retention costs within a run + +Execution histories and repeated serialization increase peak memory, and retained +interaction files and warnings can accumulate after write failures. Reduce +duplicate representations and define retention and failure behavior appropriate to +opt-in capture. +[Resources §6](05-resources.md#6-debug-capture-adds-memory-and-disk-pressure) + +### 34. Account for cumulative correction-repair history and work + +Each rejected candidate can start its own bounded conversation and repeat the +original prompt history, with additional revalidation. Measure total requests and +bytes across branches before deciding on changes to context or run-level budgets. +[Resources §7](05-resources.md#7-correction-repair-replays-growing-history-under-per-correction-budgets) + +### 35. Avoid rebuilding growing normalization prefixes + +Merge estimation and category accumulation repeatedly copy and scan the same +growing text and category prefixes. Reuse incremental work while preserving exact +text, category order, and the configured limit. +[Efficiency §1](02-efficiency.md#1-normalization-repeatedly-copies-and-scans-growing-merge-runs) + +### 36. Skip validation context work beyond the usable budget + +Optional context is serialized even when required fields already exceed budget. +Share trimming and batching policy, stop measuring context that cannot fit, and +keep serialized measurement as an independent reference for the optimized path. +[Efficiency §4](02-efficiency.md#4-validation-measures-optional-context-that-cannot-fit) · +[Equivalence §1](10-equivalence.md#1-share-validation-budget-policy-across-measurement-paths) + +### 37. Reuse checked processing selections and matching views + +Preflight and execution separately decide active roles, and repeated profile or +glossary selections repeat inspection, copying, and preparation. Carry one checked +processing plan and reuse immutable results for equivalent selections. +[Efficiency §6](02-efficiency.md#6-repeated-pipeline-selections-duplicate-setup-work) · +[Boundaries §4](11-boundaries.md#4-carry-one-checked-processing-plan-from-preflight-into-execution) + +### 38. Select glossary context by identity membership + +The validation context builder materializes each matched occurrence for every +contributor and then deduplicates them. Use a membership path for context and +preserve occurrence counts for protection. +[Efficiency §3](02-efficiency.md#3-validator-glossary-context-expands-every-occurrence-into-every-contributor) + +### 39. Avoid rescanning sections for skipped edits + +Apply-time filtering searches the original chunk for every skipped proposal. Reuse +a segment lookup and preserve stale-conflict and filtering distinctions. +[Efficiency §2](02-efficiency.md#2-application-reporting-searches-the-source-chunk-for-each-skipped-edit) + +## Ownership and maintainability + +### 40. Use one validator contract and one owner for decision semantics + +Runner-side applicability and verdict handling overlap with validator +implementations. Consolidate the interface and acceptance rules, and remove the +unused validation request envelope, segment ID field, and result name copy. +[Complexity §3](03-complexity.md#3-put-validator-applicability-and-decision-meaning-at-their-owning-boundary) · +[Boundaries §1](11-boundaries.md#1-give-the-validator-runtime-interface-one-owner) · +[Dead code §4](12-deadcode.md#4-drop-the-unconsumed-validation-request-envelope) + +### 41. Carry structured failure facts through model operations and reporting + +Proposal, validation, and repair repeat class and reason extraction, and report +counts reclassify failures from reason codes. Carry typed outcome facts forward +while preserving role-specific recovery and fatal handling. +[Complexity §7](03-complexity.md#7-give-reporting-one-source-for-operation-classification-and-counts) · +[Equivalence §4](10-equivalence.md#4-share-structured-failure-facts-across-model-operations) + +### 42. Keep required output publication separate from optional debug retention + +The output session combines unrelated lifecycles. Give required-output preparation +and publication a clear owner, share regular-file staging mechanics for transcript +and reports, and expose debug setup through its own API. +[Complexity §9](03-complexity.md#9-clarify-output-preparation-publication-and-failure-ownership) · +[Equivalence §2](10-equivalence.md#2-share-regular-file-staging-between-transcript-and-report-publication) · +[Boundaries §7](11-boundaries.md#7-separate-required-publication-from-retained-debug-artifacts) + +### 43. Inject one interaction diagnostics contract + +Proposal, validation, and repair duplicate path types and writer wiring. Supply a +diagnostic sink from the adapter boundary, with role-specific payloads, lazy +redaction inputs, and nonfatal write warnings. +[Complexity §4](03-complexity.md#4-separate-validation-batch-assessment-from-the-diagnostic-writer) · +[Equivalence §5](10-equivalence.md#5-give-optional-interaction-artifacts-one-writer-contract) · +[Boundaries §6](11-boundaries.md#6-inject-interaction-diagnostics-at-the-adapter-boundary) + +### 44. Simplify structured-call completion and remove obsolete record fields + +Share finalization across ordinary calls and coordinated turns, and remove +obsolete error-kind state, response usage copies, and duplicate callback payloads. +Keep typed causes and live execution and artifact evidence. +[Complexity §5](03-complexity.md#5-make-the-structured-clients-call-lifecycle-explicit) · +[Dead code §5](12-deadcode.md#5-remove-structured-call-fields-superseded-by-execution-observations) + +### 45. Retire the test-only direct continuation branch + +The supported repair path uses the coordinator. Move direct-continuation +assertions about sibling isolation and structural repair to coordinated calls, +then remove the unused request branch. +[Complexity §5](03-complexity.md#5-make-the-structured-clients-call-lifecycle-explicit) · +[Dead code §1](12-deadcode.md#1-retire-the-test-only-direct-continuation-path) + +### 46. Use a single proposal handoff and test real runner indexing + +The generator builds enriched proposals the production wrapper discards. Give the +runner index ownership, remove the parallel enrichment, and assert indices under +observed out-of-order completion instead of in the test-only composition harness. +[Complexity §6](03-complexity.md#6-use-a-single-proposal-handoff-and-wire-repair-capability-explicitly) · +[Testing §6](08-testing.md#6-concurrency-fixtures-leave-some-schedules-unproved) · +[Testing §9](08-testing.md#9-delete-proposal-order-assertions-on-the-test-only-composition-harness) · +[Dead code §2](12-deadcode.md#2-remove-proposal-enrichment-that-the-live-handoff-discards) + +### 47. Centralize request-local segment reference resolution + +Initial proposals and repair revisions duplicate the same local-position lookup. +Preserve raw references, stable proposal identity, and revalidation for retargeted +edits. +[Equivalence §3](10-equivalence.md#3-resolve-model-segment-references-in-one-place) · +[Complexity §6](03-complexity.md#6-use-a-single-proposal-handoff-and-wire-repair-capability-explicitly) + +### 48. Give one repair branch a clear execution and result boundary + +Branch coordination, previews, revision validation, accounting, and diagnostics +share state inside the section loop. Separate branch state and make repair prompt, +exchange capture, and coordinator capability explicit. +[Complexity §2](03-complexity.md#2-separate-one-repair-branch-from-the-sections-repair-loop) · +[Complexity §6](03-complexity.md#6-use-a-single-proposal-handoff-and-wire-repair-capability-explicitly) + +### 49. Define concurrency and ownership in module and validator contracts + +Workers share module and validator instances and borrow section and glossary data. +Specify concurrent calls, read-only borrowed inputs, and cooperative cancellation +at the interface boundary. +[Concurrency §8](04-concurrency.md#8-shared-module-and-validator-ownership-is-implicit-at-their-interfaces) + +### 50. Consolidate root and per-module configuration rules + +Resolution and validation repeat role defaults, null and inheritance rules, and +field checks. Share the rules while keeping path-specific diagnostics and +configuration provenance. +[Complexity §10](03-complexity.md#10-share-root-and-per-module-configuration-rules) · +[Equivalence §6](10-equivalence.md#6-use-one-set-of-checks-for-inherited-configuration-fields) + +### 51. Unify transcript conversion and retire redundant parser wrappers + +Source-to-canonical conversion is duplicated across the CLI, a lenient wrapper, +and fixtures. The strict test-only wrapper panics on omitted IDs. Use one +conversion and the supported decoder, and preserve independent fixture +expectations. +[Efficiency §9](02-efficiency.md#9-the-strict-transcript-parser-panics-on-a-missing-id) · +[Testing §12](08-testing.md#12-consolidate-normalization-fixtures-at-the-domain-and-parser-owners) · +[Boundaries §9](11-boundaries.md#9-put-transcript-conversion-and-output-shape-at-their-owning-boundaries) · +[Dead code §8](12-deadcode.md#8-remove-the-transcript-parser-variants-that-only-tests-call) + +### 52. Give public transcript encoders one segment projection + +The output registry implements the envelope and delegates the bare form to the +schema package. Share the field projection at the output boundary and verify both +wire shapes independently. +[Boundaries §9](11-boundaries.md#9-put-transcript-conversion-and-output-shape-at-their-owning-boundaries) + +### 53. Use one simple token estimate across text-processing packages + +Normalization and chunking implement the same word and punctuation heuristic. +Share the counter and preserve consumer-specific budgets and independent +expected-count tests. +[Equivalence §7](10-equivalence.md#7-use-the-same-simple-token-counter-for-text-estimates) + +### 54. Centralize transcript cloning + +Runner and proposal application duplicate deep-copy code with different +empty-category handling. Share the copy operation while keeping both caller +ownership boundaries and verifying independence from fixture data. +[Equivalence §8](10-equivalence.md#8-centralize-transcript-copies-without-moving-the-copy-boundaries) + +### 55. Assemble built-in modules at the composition boundary + +The framework registry imports all concrete modules even though the runner +consumes a factory interface. Keep config keys independent of implementations and +place production construction with the CLI or built-ins. +[Boundaries §3](11-boundaries.md#3-put-production-module-construction-at-the-composition-boundary) + +### 56. Merge shared prompt variables once per model call + +Processing loads the embedded instruction values twice. Keep processing precedence +and the missing protected-term default in one pass, and preserve caller precedence +for inspection. +[Dead code §6](12-deadcode.md#6-resolve-shared-prompt-variables-once-per-model-call) + +### 57. Clarify what the inherited progress flag does in processing + +`process` advertises progress messages but supplies no producer. Define its +behavior or clarify process help while preserving acceptance for existing scripts. +[Dead code §10](12-deadcode.md#10-resolve-the-inherited-progress-flag-for-process) + +## Test maintenance and dead code + +### 58. Test registered validator roles and embedded assets through their behavior + +Consolidate redundant execution-class checks and assert required prompt identities +and preparability. Keep schema identity, diagnostic metadata, and protective-copy +coverage. +[Testing §10](08-testing.md#10-consolidate-validator-registry-and-asset-metadata-assertions) + +### 59. Consolidate overlapping normalization fixtures + +Two different-speaker fixtures protect the same rejection. Keep the distinct +domain cases and meaningful merge, text, and category assertions. +[Testing §12](08-testing.md#12-consolidate-normalization-fixtures-at-the-domain-and-parser-owners) + +### 60. Focus integration tests on decoded artifacts and independent output choices + +Assert decoded IDs and evidence associations and use smaller fixtures for +duplicate reporting and debug combinations. Keep a full scenario for attribution +through repair and later failure. +[Testing §13](08-testing.md#13-narrow-integration-assertions-to-their-distinct-contracts) + +### 61. Remove abandoned test support and unused fixture inputs + +The orphan test-support package, unused CLI and runner helpers, and legacy +glossary fixture input have no current callers. Preserve compile-time interface +fixtures and active behavior assertions. +[Dead code §9](12-deadcode.md#9-clean-up-abandoned-test-support) · +[Testing §13](08-testing.md#13-narrow-integration-assertions-to-their-distinct-contracts) + +### 62. Remove unreachable merge and file helpers + +The uncalled merge predicate and standalone JSON and file-write helpers duplicate +or bypass the live normalization, schema, and output paths. +[Dead code §7](12-deadcode.md#7-remove-orphaned-normalization-and-file-helpers)