608 lines
35 KiB
Markdown
608 lines
35 KiB
Markdown
# 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 12 source audits contain 110 numbered findings. This catalog consolidates them
|
||
into 65 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.
|
||
|
||
The [assessment and decision register](assessment.md) evaluates every entry using
|
||
the maintainer-approved taxonomy and separates ready remediation from technical
|
||
investigation and pending policy decisions. Consult it before planning changes;
|
||
source-audit recommendations are evidence and proposals, not authorization.
|
||
The three WONTFIX scopes recorded here remain controlling.
|
||
The focused [redaction-removal audit](14-redaction.md) applies resolved D1:
|
||
the earlier redaction remedies below are superseded, and #63–65 add distinct
|
||
cleanup work. Entry numbers and existing anchors are retained for traceability.
|
||
|
||
## 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.
|
||
|
||
**WONTFIX.** PromptKit inherits the standard `net/http` client's default redirect
|
||
and credential-forwarding behavior. Audita accepts those defaults for the
|
||
built-in transport.
|
||
[Security §2](07-security.md#2-provider-redirects-can-cross-the-configured-transport-boundary)
|
||
|
||
### 3. Protect credentials inside nested debug responses
|
||
|
||
**Superseded by D1.** The original observation tested the withdrawn redaction
|
||
requirement. Remove Audita's substitution package and use direct artifact
|
||
serialization; retain useful responses, including malformed content. Retire
|
||
masking-only tests and documentation while preserving evidence-fidelity and
|
||
write-failure coverage. Credential discovery and repair/CLI consumers are covered
|
||
by #63–65; no nested sanitizer or response-omission policy is selected.
|
||
[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) ·
|
||
[Redaction removal §2](14-redaction.md#2-replace-sanitizing-serialization-with-direct-encoding) ·
|
||
[Redaction removal §7](14-redaction.md#7-retire-obsolete-assertions-and-documentation-without-losing-coverage)
|
||
|
||
### 4. Make debug artifact permissions private by default
|
||
|
||
**Prior remedy withdrawn under D1.** Operators own artifact access and sharing;
|
||
hostile local filesystem access is outside the selected threat model. The focused
|
||
audit found ordinary creation and filename handling to retain, not a redundant
|
||
private-root mechanism. Leave current locations and modes unchanged in this
|
||
cleanup. Any future default change needs an independent justification.
|
||
[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, and FIFO or stdout delivery can stay blocked
|
||
after cancellation.
|
||
|
||
**WONTFIX (interrupting already-blocked I/O).** The standard file operations used
|
||
here take no context, and `io.Writer` offers no general interruption mechanism.
|
||
Audita accepts that those calls can remain blocked until I/O can proceed.
|
||
|
||
The application still owns the outcome when control returns. Check cancellation
|
||
before publishing a regular file and after stream delivery returns so a canceled
|
||
run exits nonzero and attempts to write failed-status reports.
|
||
[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. **Resolved D2:** destination isolation remains the caller’s
|
||
responsibility. Retain current report placement and document distinct report
|
||
directories for concurrent jobs or retained run histories. Automatic per-run
|
||
placement, locking, waiting, and competing-writer rejection are outside this
|
||
remediation. Correct publication to checked destinations remains #1’s concern.
|
||
[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. Under resolved D1, remove the post-serialization redactor and
|
||
serialize the typed report directly. Keep schema/scalar fidelity coverage; do
|
||
not build a more selective sanitizer.
|
||
[Correctness §9](01-correctness.md#9-credential-redaction-can-change-the-ordinary-yaml-schema) ·
|
||
[Redaction removal §2](14-redaction.md#2-replace-sanitizing-serialization-with-direct-encoding)
|
||
|
||
### 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.
|
||
|
||
**WONTFIX (Unicode behavior of `\b`).** Go's `regexp` defines `\b` as an ASCII
|
||
word boundary. Audita accepts that definition for the standard regexp engine.
|
||
|
||
Configured aliases with punctuation at their edges still need a glossary matching
|
||
rule for protection and context selection, even when their letters are ASCII.
|
||
[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. Preserve native
|
||
inspection behavior; retired application-wide masking expectations are not an
|
||
additional acceptance criterion.
|
||
[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 actionable native setup detail and preserve the underlying
|
||
typed cause and failure classification. D1 removes the blanket restriction on
|
||
cause presentation; ordinary compact report projections remain useful.
|
||
[Error handling §3](06-error-handling.md#3-missing-required-credentials-produce-a-generic-setup-message) ·
|
||
[Redaction removal §6](14-redaction.md#6-simplify-cli-presentation-while-retaining-typed-failure-ownership)
|
||
|
||
### 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.
|
||
**Resolved D3:** preserve PromptKit's configured waiting and recoverable rejection.
|
||
Do not add an outer capacity-retry loop, duplicate backend limiter, or eventual-
|
||
admission promise. Current scheduling-dependent rejection order is not a
|
||
compatibility requirement. Verify memory use, actual contention, and cancellation
|
||
while improving local scheduling; any future admission-policy gap belongs upstream.
|
||
[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
|
||
write the acquired source bytes directly to its debug snapshot instead of
|
||
reconstructing them for redaction. Keep parsed/normalized views separate.
|
||
**Resolved D4:** improve memory use without adding an application-level
|
||
transcript-size limit. Calling integrations own their upload/process budgets;
|
||
preserve accepted input formats and stream support.
|
||
[Redaction removal §3](14-redaction.md#3-save-the-acquired-source-snapshot-without-reconstructing-it) ·
|
||
[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 serialization, and consolidate equivalent warnings
|
||
with counts and affected-artifact information. **Resolved D5:** preserve requested
|
||
evidence, self-contained interactions, nonfatal failures, and continued best-effort
|
||
capture. Add no quotas, automatic deletion, or automatic stopping after write
|
||
failures; operators own retention and cleanup.
|
||
[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. **Resolved D6:** retain
|
||
full conversation history and existing per-correction limits; add no aggregate
|
||
budgets or context reduction at this time. Measure cumulative work and remove
|
||
unnecessary local duplication. Revisit behavior changes only if production
|
||
evidence demonstrates a need.
|
||
[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 and
|
||
nonfatal write warnings. Remove secret-provider assertions, lazy discovery
|
||
closures, combined-role secret lists, and preflight/writer credential arguments.
|
||
Keep artifact association and optional write-error reporting.
|
||
[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) ·
|
||
[Redaction removal §4](14-redaction.md#4-remove-secret-plumbing-from-writer-and-preflight-contracts)
|
||
|
||
### 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. Remove masking expectations without discarding
|
||
the independent artifact and outcome assertions mixed into those fixtures.
|
||
[Testing §13](08-testing.md#13-narrow-integration-assertions-to-their-distinct-contracts) ·
|
||
[Redaction removal §7](14-redaction.md#7-retire-obsolete-assertions-and-documentation-without-losing-coverage)
|
||
|
||
### 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.
|
||
[Redaction removal §7](14-redaction.md#7-retire-obsolete-assertions-and-documentation-without-losing-coverage) ·
|
||
[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)
|
||
|
||
## Additional cleanup after resolved D1
|
||
|
||
### 63. Remove redaction-only credential discovery and tracking
|
||
|
||
Audita enumerates captured profiles/backends, reads credential environment values,
|
||
caches names, and tracks prepared role names under a mutex solely for substitution.
|
||
Remove that state and the secret-source methods after updating their consumers.
|
||
Preserve PromptKit authentication, prepared evidence, execution synchronization,
|
||
and native inspection behavior.
|
||
[Redaction removal §1](14-redaction.md#1-remove-credential-discovery-and-tracking-used-only-for-substitution)
|
||
|
||
### 64. Preserve validator explanations in repair feedback
|
||
|
||
Repair rewrites validator explanations using both roles' credential values even
|
||
with debug off. Remove this transformation and use domain feedback directly.
|
||
Retain proposal association, unavailable-assessment semantics, and the existing
|
||
bounded repair/revalidation behavior.
|
||
[Redaction removal §5](14-redaction.md#5-stop-rewriting-validator-explanations-sent-to-repair)
|
||
|
||
### 65. Remove credential substitution from CLI presentation
|
||
|
||
Preparation and completion paths scrub warnings, errors, and announced paths;
|
||
completion discovers credentials even with reports/debug disabled. Use direct
|
||
CommandKit presentation, remove obsolete arguments, and retain typed causes,
|
||
reporting modes, exit status, and required-output failure handling. Coordinate
|
||
with #25 for setup detail still hidden by the separate failure wrapper.
|
||
[Redaction removal §6](14-redaction.md#6-simplify-cli-presentation-while-retaining-typed-failure-ownership)
|