521 lines
30 KiB
Markdown
521 lines
30 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 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)
|