diff --git a/docs/adr/0003-module-focus-and-editorial-acceptance.md b/docs/adr/0003-module-focus-and-editorial-acceptance.md new file mode 100644 index 0000000..f9ef694 --- /dev/null +++ b/docs/adr/0003-module-focus-and-editorial-acceptance.md @@ -0,0 +1,59 @@ +# ADR 0003: Module focus and editorial acceptance + +**Status:** Accepted + +**Date:** 2026-11-11 + +## Context + +Audita gives each correction module a focused task. A prompt review suggested +making that task's scope an acceptance condition, because validators can accept +minor editorial changes that the proposing module was not asked to make. + +The maintainer's practical testing established why this difference is deliberate. +Models persistently propose minor editorial cleanup when it is clearly warranted +in the supplied text. Instructions strict enough to suppress that cleanup also +suppress desirable edits. Enforcing exclusive module scopes would therefore +trade away useful corrections to achieve a separation that does not serve the +application's editorial goals. + +## Decision + +Module scope guides the corrections Audita asks a model to propose. It is not an +exhaustive boundary on acceptable edits. Minor editorial cleanup is permitted +across modules and their validators even when the proposal prompt does not +request it. + +Validators must not reject an otherwise acceptable minor editorial change solely +because it falls outside the originating module's requested focus. Existing +checks for applicability, protected terms, meaning, and other domain concerns +continue to apply. This allowance does not guarantee that any particular edit +passes validation or application, nor does it authorize arbitrary rewriting. + +Proposal, validation, and repair instructions may differ to serve their roles. +Their consistency should be assessed against this distinction, rather than by +requiring identical lists of allowed edits. Repair feedback should not turn +module focus into an exclusive acceptance rule. + +## Alternatives considered + +**Strict module-aware acceptance**, whether implemented in shared validators, +separate review definitions, or an additional scope check, would make stage +boundaries easier to describe. It is rejected because the maintainer's testing +shows that suppressing incidental cleanup also suppresses desirable work. + +**Request every kind of cleanup in every module** would align proposal requests +with the broader acceptance policy, but would dilute the focused tasks. Permitting +incidental cleanup does not require asking each stage to perform every task. + +## Consequences + +An edit accepted outside a module's requested focus is not, by itself, a design +defect. Prompt maintenance and evaluation should preserve useful corrections +while checking substantive editorial quality. They should not introduce strict +scope enforcement as an apparent consistency fix. + +The [architecture policy](../policy/architecture.md#correction-and-concurrency-invariants) +records the boundary. Reconsidering this accepted decision requires new evidence +and explicit supersession under the ADR lifecycle, rather than rediscovering the +same prompt/validator difference during each review. diff --git a/docs/adr/README.md b/docs/adr/README.md index 83bc702..9f0f55a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -6,6 +6,8 @@ accepted 2026-10-07. - [ADR 0002: Glossary configuration and processing readiness](0002-glossary-configuration-and-preflight.md) — accepted 2026-11-10. +- [ADR 0003: Module focus and editorial acceptance](0003-module-focus-and-editorial-acceptance.md) — + accepted 2026-11-11. Use the [documentation policy's ADR lifecycle](../policy/documentation.md#architecture-decision-records) diff --git a/docs/internal/prompts.md b/docs/internal/prompts.md index 4d3500b..d66f316 100644 --- a/docs/internal/prompts.md +++ b/docs/internal/prompts.md @@ -17,6 +17,13 @@ supplies the embedded instruction fragments for those names. Processing supplies Audita's response-schema contract separately. The operator's prompt definition controls which variables its template uses. +Proposal focus and validator acceptance intentionally differ: minor editorial +cleanup may be accepted even when the proposing module was not asked to perform +it. Follow the [architecture boundary](../policy/architecture.md#correction-and-concurrency-invariants) +when maintaining proposal, validation, and repair instructions; the difference +alone is not a reason to tighten validation. The testing rationale is recorded in +[ADR 0003](../adr/0003-module-focus-and-editorial-acceptance.md). + For a standard request preview or validation, select a native PromptKit profile and supply the template variables used by the selected prompt. The shipped proposal definitions use `TranscriptDescriptionBlock`, `GlossaryJSON`, diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 3254e3f..6c0b261 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-11 **Upstream Source:** [Standard Repository Policies architecture](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) ## Purpose And Ownership @@ -72,6 +72,12 @@ hidden global state. ## Correction and Concurrency Invariants +- Module focus guides proposal generation; it is not an exclusive acceptance + boundary. Validators permit otherwise acceptable minor editorial cleanup even + when the originating module did not request it. Existing applicability, + protection, and meaning checks still apply. See + [ADR 0003](../adr/0003-module-focus-and-editorial-acceptance.md) for the empirical + rationale and rejected strict-scope alternative. - Treat LLM responses as nondeterministic inputs. Preserve deterministic proposal indexing, validator ordering, transcript mutation, reports, and serialization. - Validate corrections before final mutation, including local proposal checks, diff --git a/docs/roadmap/prompt-quality.md b/docs/roadmap/prompt-quality.md index 58b0646..f3ef44b 100644 --- a/docs/roadmap/prompt-quality.md +++ b/docs/roadmap/prompt-quality.md @@ -2,9 +2,9 @@ **Updated:** 2026-11-11 -**Status:** Proposed discussion roadmap; decisions and implementation pending. -Work through the topics below in order. Recommendations are starting points for -discussion, not newly adopted restrictions or guarantees. +**Status:** Topic 1 resolved in ADR 0003; topics 2–6 remain for discussion. +Work through the remaining topics in order. Their recommendations are starting +points for discussion, not newly adopted restrictions or guarantees. ## Baseline and Intended Direction @@ -21,19 +21,13 @@ roles, useful rejection feedback, and maintainability. ## Discussion and Work Order -### 1. Align Validation with Module Scope +### 1. Module Focus and Editorial Acceptance — Resolved -The grammar proposal permits formatting and the narrow `a`/`an` exception, -while its editorial validator also permits homophone corrections, dysfluency -removal, and combinations of those changes. An edit can satisfy that validator -while violating the proposing module's instructions. - -**Recommendation:** supply the originating module's allowed edits to editorial -validation and assess them alongside meaning preservation. Prefer reusing the -shared validator where practical. This needs request-context wiring as well as -prompt changes; a prompt rewrite alone cannot supply missing scope information. -Discuss the scope contract and shared versus specialized definitions first. -See [modules](../internal/modules.md) and [validators](../internal/validators.md). +The intentional distinction between requested module focus and acceptance of +minor editorial cleanup is recorded in +[ADR 0003](../adr/0003-module-focus-and-editorial-acceptance.md). The maintainer's +testing found that strict scope instructions also suppress desirable edits. +Apply the accepted distinction throughout the remaining prompt work. ### 2. Make Rejection Reasons Useful for Repair @@ -52,8 +46,9 @@ Withdrawal is already explicit. Clarify when the model should use it and how it should respond when the original evidence remains insufficient. **Recommendation:** ask the model to reassess the correction from the supplied -evidence, preserve module scope, and withdraw unsupported proposals. Address the -risk that numerical confidence feedback merely encourages raising the score. +evidence, retain the module's focus and the accepted editorial allowance, and +withdraw unsupported proposals. Address the risk that numerical confidence +feedback merely encourages raising the score. Do not automatically prohibit confidence-only revisions: legitimate reassessment is possible. Discuss and evaluate that behavior before adding a business rule. Retain the agreed full-history conversation model and existing repair lifecycle. @@ -63,9 +58,10 @@ Retain the agreed full-history conversation model and existing repair lifecycle. Restrictions and examples recur across proposal, validation, and repair assets; the grammar prompt repeats its word-substitution boundary several ways. -**Recommendation:** distinguish shared editing principles, module scope, and -task-specific response contracts. Use small shared fragments where they reduce -drift. Replace some repetitive example lists with contextual contrasts, such as +**Recommendation:** distinguish shared editing principles, requested module focus, +validator acceptance criteria, and task-specific response contracts. Use small +shared fragments where they reduce drift. Replace some repetitive example lists +with contextual contrasts, such as accidental repetition versus deliberate emphasis. Preserve useful distinctions; shorter prompts alone are not the objective. Discuss what belongs in shared fragments and what remains local to each definition. @@ -93,7 +89,7 @@ Use the preceding decisions and evaluation evidence to discuss these in order: 1. **Grammar naming and scope:** the current module is close to copy editing, with an isolated article exception. Decide whether its name and scope convey - the intended product behavior. + the intended requested work, preserving the accepted editorial allowance. 2. **Glossary/homophone overlap:** assess the benefit of their overlapping remit and repeated glossary passes before changing the default sequence. 3. **Language and examples:** decide whether spoken English and campaign-specific