audita/docs/roadmap/span-deletion.md

Consistent Span Deletion

Last updated: 2026-09-25

Status: Implemented. This document owns the desired behavior and user intent. The historical implementation plan records the concrete steps, selected implementation details, and completion evidence.

Purpose and User Intent

Align proposal prompts, the LLM response schema, internal validation, and application behavior so legitimate text-span deletions can be considered and applied through the ordinary correction workflow. An empty replacement should not trigger structural repair merely because it is empty, nor invalidate other usable corrections returned alongside it.

This is a consistency fix within Audita's current editing scope. It does not authorize whole-segment removal, broaden module responsibilities, or introduce new recovery machinery. The accepted resilience behavior remains in effect, including partial success, fixed chunks, and validation before mutation.

Historical Baseline (0b6cd98)

The source reviewed at 0b6cd98 contains a mismatch:

• The spoken-word prompt permits removing fillers and asks for the exact affected span and replacement, without explaining how to represent deletion. Grammar permits punctuation and spacing changes, which can also naturally involve deletion.
• The shared correction response schema requires corrected_text to have at least one character. Every built-in proposal module uses that schema. An empty replacement invalidates the response before Audita evaluates individual proposals.
• PromptKit performs bounded structural repair. If repair does not produce a valid response, the proposal operation fails and yields no candidates, including otherwise valid proposals in the same response. The current resilience path records the error and continues other work.
• CorrectionProposal already allows empty replacement text. The preview/application logic supports literal span deletion when the resulting segment remains nonblank.
• Domain shape checks currently reject whitespace-only original spans, although the response schema permits them and grammar prompts permit spacing cleanup. This is another restriction to align with the target contract below.
• The validator named non_empty_corrected_text actually checks the resulting segment, not the replacement string. Both this check and application prevent a segment from becoming empty or whitespace-only. Application changes segment text; it does not remove segment records.

A temporary controlled-provider review reproduced whole-response rejection for an empty replacement alongside a valid correction, and immediate schema acceptance for a space-only replacement. Existing proposal tests confirm internal support for partial deletion and rejection of blank resulting segments. These observations explain a plausible production failure mechanism; they do not establish the cause of any particular historical incident without its payload and running version.

Target Correction Contract

• original_text identifies an existing, nonempty literal span in the current target segment. Whitespace-only spans are eligible; an empty string identifies no source span and remains invalid. Matching and ambiguity checks still apply under the module's replacement policy: require_unique for grammar, spoken-word, and homophones; replace_all for glossary.
• corrected_text remains a required string. An empty string means delete the identified span; it does not mean remove the segment record or skip validation. Missing fields and non-string values remain structurally invalid.
• After applying a correction, the segment must contain non-whitespace text. Enforce this using the source segment and replacement result in Audita, not a minimum replacement length in the structural schema.
• Every accepted deletion passes the same required validators as other edits in its module, including confidence, protected terms, editorial review, and meaning preservation where applicable. Empty replacement is neither automatic approval nor an automatic rejection.
• Application preserves segment identity, speaker, timing, membership, ordering, and fixed chunk boundaries. Recheck applicability against text produced by earlier accepted corrections, retaining existing conflict handling.
• Preserve literal replacement behavior. Prompts should select spans and replacements that handle adjacent whitespace and punctuation appropriately; this feature does not add automatic trimming or a second normalization pass. Neither side of a correction is rejected solely for containing only whitespace. For example, reducing a uniquely identified run of two spaces to one space may be appropriate; validity still depends on the resulting text and domain checks.

Preserve the intended safeguards and outcomes, not every detail of the current implementation. Validator ordering, internal structure, and payload construction may change when needed to achieve this consistent contract. Existing behavior or a passing test does not justify retaining a conflicting restriction.

Illustrative cases:

Segment	Original span	Replacement	Intended handling
uh hello	uh	empty string	Structurally valid; may produce hello after required validation.
uh hello	uh hello	hello	Remains a valid representation of the same cleanup, subject to validation.
hello world	two spaces	one space	Eligible spacing correction, subject to unique matching and required validation.
uh	uh	empty string	Structurally valid proposal, then filtered because the resulting segment would be blank.
hello world	hello world	spaces only	Filtered because the resulting segment would be blank.

These examples describe eligibility and mechanical results, not unconditional editorial approval. An unchanged segment or valid empty correction list remains a successful no-change outcome.

Prompt and Module Alignment

Review relevant prompt definitions for consistency and edit only those needing clarification. Where needed, explain empty-string deletion, whitespace-only spans, and the resulting-segment limit with a concise, module-appropriate example. The model should omit a correction that would leave a blank segment rather than invent padding or replacement content. Consistent guidance is the goal; adding deletion language to every prompt is not a requirement.

Retain each module's existing scope:

• Spoken-word cleanup can propose appropriate filler or dysfluency deletion while preserving substantive content and intentional emphasis.
• Grammar can propose permitted punctuation or spacing deletion; allowing an empty replacement does not authorize word removal or spoken-word cleanup.
• Glossary and homophone modules retain their existing correction purposes. Shared deletion syntax does not grant them new editorial responsibilities.

Review the active LLM-validator prompts and their input construction as well as proposal prompts. Validators must understand the before/after effect of deletion and assess it under their existing criteria. A correct negative editorial decision remains ordinary processing, not a defect that should be regenerated until approved.

The resulting-segment validator's name and documented identity should describe that responsibility accurately, rather than imply that the replacement string itself must be nonempty. Preserve the existing blank-result failure reason and safeguard while making that deliberate identity change; current chain position and preview implementation are not independent product requirements.

Outcomes and Reporting

A legitimate deletion is an ordinary correction. Empty replacement alone must produce neither structural repair nor a recovery classification. If another problem required successful repair or filtering, retain that actual recovery.

A schema-valid proposal that would blank its stage-input segment is a defective proposal handled through existing safe filtering. Preserve the empty_resulting_segment reason and consolidated proposals_filtered recovery behavior; other usable proposals in the response continue through required validation. Ordinary editorial rejection remains debug evidence rather than a model error or filtering recovery.

A stage can propose several edits to one segment in the same response. Each edit is evaluated against the stage input, then approved edits are applied sequentially. If a proposal was applicable to that input but an earlier accepted edit makes it unsafe, skip it as an apply-time conflict. Do not count that conflict as a defective proposal, model error, or filtering recovery. For example, in "uh um", deleting "uh " and deleting "um" each leaves text individually; after the first deletion, the second must be skipped to prevent a blank result. Retain the skipped decision in debug evidence. The existing runner already distinguishes this situation.

Debug evidence must accurately retain the empty replacement and the corresponding validation/application outcome. Ordinary reports retain their existing counts and purpose; no new report schema, incident category, or deletion-specific counter is needed. Unrelated structural defects may still exhaust PromptKit repair and produce an error for the operation, as today.

Acceptance Criteria

• A controlled valid response containing an empty replacement reaches Audita's domain validation without structural repair solely due to that empty string.
• A permitted span deletion can pass the required validators and reach the final transcript while preserving segment metadata and fixed chunk membership.
• A mixed response can apply an approved deletion and another approved correction; an empty replacement does not invalidate the whole response.
• A proposal that would blank its stage-input segment is filtered independently, retains the existing reason, and does not prevent unrelated valid candidates from succeeding. A proposal made unsafe only by an earlier accepted edit is skipped without adding an error or filtering recovery; a blank result is still prevented and the conflict remains visible in debug evidence.
• A uniquely matching whitespace-only original span can reach validation and application. Empty originals remain invalid, ambiguous matches remain subject to module policy, and whitespace-only resulting segments remain disallowed.
• Protected-term and meaning-changing deletions remain subject to their normal rejection rules. No candidate bypasses required validation.
• A deletion needing no recovery counts as an ordinary applied correction; actual repair/filtering and editorial rejection retain their existing classifications. Debug evidence represents the empty replacement faithfully.
• Schema and domain tests distinguish an empty string from missing/non-string replacement values and distinguish empty replacement from blank resulting text.
• Prompt guidance and validator naming express the same contract as the code. Tests protect outcomes rather than exact prompt prose or incidental formatting.

Use deterministic, offline controlled responses for behavioral integration tests; no live-provider or paid evaluation is a prerequisite. Representative production examples can inform prompt quality without expanding this into an evaluation framework or guaranteeing that models always follow the instructions.

Deferred Work

Whole-segment removal is only potential future work and first requires deciding whether its benefit warrants implementation. Domain-aware regeneration and independent whole-pipeline traversal also remain in future.md. This feature changes neither retry budgets nor the Audita/PromptKit ownership boundary and requires no upstream library feature.

Implementation sequencing and concrete names belong to the historical implementation plan. The target remains consistent deletion of spans within surviving segments, with no new operator controls or report types.