**Blocker: Assess #3586348+s before proceeding on this issue.** ## Follow-up issue Follow-up to: #3586363 Child of the "Before 1.0" triage in #3586363+s. Improves selection transparency, conditional-subcontext failure visibility, and debug diagnostics before 1.0. **Scope:** #3, #4, #9 from the Before 1.0 list in #3586363. **Non-goals:** documentation/trust/compatibility work (#1, #2, #5, #6, #8 — separate issue), performance benchmarks (#7 — 1.1), usage vs observability (#10 — #3567803 / #3586213), rich selection diagnostics UI or persistence ([#3586242](https://git.drupalcode.org/project/ai_context/-/work_items/3586242)). ## Problem / motivation Selection behavior is mostly correct, but site builders and developers cannot always tell **what was selected, what was dropped, and why**. Three gaps remain before 1.0: 1. **Truncation semantics are unclear** — “Always include” and required subcontext children can still be truncated by item or token limits, but UI help and docs do not state this plainly. 2. **Conditional subcontext failures are hard to diagnose** — fail-closed behavior exists, but logging and admin guidance are inconsistent. 3. **Debug output is fragmented** — useful IDs exist on the result object, but there is no single concise debug summary for a selection run. These packages share selector/renderer logging, admin help text, debugging documentation, and kernel tests. One forced-truncation test can cover much of #3 and #9. ## Work packages ### #3 — Clarify truncation of always-included / required context “Always include” gives an item **priority** over ordinary matching; it does **not** guarantee the complete item reaches the prompt. - Always-included items remain subject to the overall **item limit**. - All items — including required subcontext children — remain subject to the **token limit** and may be shortened or omitted during rendering. **Tasks:** - State this directly beside the relevant controls (agent config, context item forms where applicable). - Update selection/scopes documentation with the same wording. - Warn against treating these settings as guaranteed delivery for compliance-critical instructions. - Add kernel tests covering truncation of always-included and required items. **Coordinate with** [#3586348](https://git.drupalcode.org/project/ai_context/-/work_items/3586348) (scope eligibility, ranking, and limits help) so help text stays consistent and does not duplicate or contradict. ### #4 — Improve conditional-subcontext failure visibility Conditional provider failures already fail closed: conditional children are excluded while required children are preserved. Visibility is the gap. **Tasks:** - Update `docs/developers/debugging.md` (and any related admin help) to cover: - missing providers - decision-cap exhaustion - invalid responses - unsupported providers - provider exceptions - Standardize warning messages to include: - parent context item ID - affected child count - reason category Do **not** log context content or provider-response content. - Add a short settings-form explanation of the conditional fallback behavior. - Add automated coverage for the important log messages. Builds on closed [#3586159](https://git.drupalcode.org/project/ai_context/-/work_items/3586159). ### #9 — Add concise selection diagnostics The result object already exposes selected and truncated item IDs; truncation warnings already identify affected IDs. For 1.0, add one **debug-only** summary log entry per selection containing: - consumer ID - selected item IDs - truncated item IDs - token usage **Must not include:** task text, context content, provider responses, or IDs rejected by access checks. **Tasks:** - Emit the summary only when debug logging is enabled. - Document the message format in debugging docs. - Add a kernel test using a forced-truncation scenario (can share fixtures with #3). Keep richer reason-by-reason diagnostics, persistence, and UI in postponed [#3586242](https://git.drupalcode.org/project/ai_context/-/work_items/3586242). ## Acceptance criteria - [ ] Always-include and required-item truncation behavior is documented in UI help and user/dev docs (#3) - [ ] Kernel tests cover truncation of always-included and required items (#3) - [ ] Conditional-subcontext failure cases are documented; warnings use a consistent format (#4) - [ ] Settings form explains conditional fallback; log-message tests pass (#4) - [ ] Debug-only selection summary logs consumer ID, selected IDs, truncated IDs, and token usage (#9) - [ ] Forced-truncation kernel test covers the debug summary (#9) - [ ] `./lint.sh` passes - [ ] No overlap with #3586242 scope (no structured diagnostics API or preview UI) ## Related issues - Parent/meta: #3586363 - Scope/limits help (coordinate): #3586348 - Conditional subcontext provider requirement (closed): #3586159 - Rich diagnostics (1.1, out of scope): #3586242 ## AI usage - [x] AI assisted issue