## Summary Follow-up to: - #3586281+s - #3586243+s - #3586197+s - #3586335+s - #3586337+s - #3586348+s After the 1.0 release, revisit how Context Control Center represents scope roles and decides which applicable context items receive priority. Earlier beta discussions considered explicit scope types, separating categorization from environmental matching, and adding a per-item inclusion mode. Those proposals should not be carried forward unchanged: the scope API, context-consumer architecture, selection pipeline, and UX may change before 1.0 is released. This discussion will begin with a fresh audit of the post-1.0 implementation, validate the remaining user problems, and recommend a coherent model before implementation issues are created. ## Background Beta testing identified several related concepts that are difficult to explain: 1. Assigning a scope can make an item applicable without guaranteeing that it reaches the final prompt. 2. Some scopes match consumer subscriptions, while others inspect the current request or entity. 3. A scope may currently participate in both contextual filtering and subscription scoring. 4. Global items, Target entity matches, and explicit inclusion overrides have different priority behavior. 5. Maximum item and token limits can remove otherwise applicable items. 6. Broad contextual matches, such as language or bundle, can apply to many items at once. 7. Site builders have limited visibility into why an item was selected, trimmed, or excluded. For beta4, the decision was to retain the subscription model, improve its documentation, and surface subscription limits. That work does not settle whether the underlying model should change after 1.0. ## Problem The system needs a model that is: - Understandable to site builders. - Predictable under item and token limits. - Extensible for custom scope plugins. - Suitable for agents and other context consumers. - Compatible with contextual inclusion and exclusion rules. - Observable enough to explain selection results. - Maintainable without multiple overlapping capability signals. - Safe to introduce on sites with existing context items and subscriptions. The previous proposal in #3586281 should be treated as historical input, not as an approved implementation specification. ## Goal Decide whether the post-1.0 scope and selection model needs architectural or behavioral changes and, if so, define a model that can be implemented through focused follow-up issues. The discussion should answer: - Does the current implementation still cause a demonstrated user problem? - Are explicit scope roles needed in the API or only in documentation and UI? - Should contextual scopes also participate in subscription ranking? - Should item authors be able to assign an inclusion priority? - What can “always,” “priority,” or “guaranteed” accurately mean when budgets apply? - How should priority classes compete when the available context exceeds the configured limits? - What selection information should be exposed to site builders and developers? ## Phase 1: Audit the post-1.0 implementation Before proposing an API, document the behavior that exists after 1.0. The audit should cover: - Scope plugin discovery and metadata. - Capability methods and interfaces. - Item scope storage. - Context-consumer subscription storage. - Contextual matching and filtering. - Subscription scoring. - Global and Target entity behavior. - Per-consumer inclusion and exclusion overrides. - Maximum item and token enforcement. - Tie-breaking and deterministic ordering. - Scope indexing and candidate prefiltering. - Subcontext inheritance. - Event subscribers and extension points. - Debugging or selection-history tools. - Existing automated test coverage. Identify any differences between the final 1.0 implementation and the model documented during beta. ## Phase 2: Validate user needs Gather concrete examples from post-1.0 use rather than assuming the beta proposals remain necessary. At minimum, evaluate: 1. **Broad policy context** “Article editorial standards” applies to every article. Determine whether ordinary ranking is sufficient or whether site builders need a stronger item-level priority. 2. **Narrow entity context** A context item targets one specific entity. Determine whether the current Target entity behavior remains appropriate and understandable. 3. **Language and site section** Many items may match a language or broad URL section. Determine whether contextual matching should filter, rank, or perform both operations. 4. **Multiple matching scopes** An item matches a use case, tag, language, and entity bundle. Determine how those matches combine and how the result should be explained. 5. **Context budget exceeded** More applicable or prioritized items exist than fit within the item or token limits. Determine which items win and what feedback the UI should provide. 6. **Different consumers** Agents, editors, automators, and other consumers may need different selection policies. Determine which behavior belongs in the shared model and which should remain consumer-specific. ## Topics for discussion ### 1. Scope roles Determine whether scopes need explicit roles such as: - Manual categorization or subscription matching. - Contextual eligibility filtering. - Context targeting. - Global applicability. - Exclusion or boundary matching. Questions: - Should one scope be allowed to perform more than one role? - Are existing capability methods sufficient? - Would role metadata improve plugin discovery, UI grouping, validation, or documentation? - Should roles be declared by plugins or inferred from capabilities? - How can the API avoid competing sources of truth? - How should custom plugins express unusual behavior? Do not derive static plugin roles from a runtime value that may be unavailable on administrative routes or requests without relevant context. ### 2. Item-level inclusion priority Determine whether context items need an author-controlled priority beyond ordinary ranking and per-consumer overrides. Possible approaches to evaluate include: - Keep the current model unchanged. - Add an item-level priority or “prefer when applicable” setting. - Reserve part of the context budget for higher-priority items. - Use weighted ranking rather than separate priority buckets. - Keep stronger inclusion controls exclusively at the consumer level. Questions: - Is importance a property of the item, the consumer, the scope match, or some combination? - Should priority apply only when every contextual filter matches? - Should priority affect all consumers? - How should inherited subcontext items behave? - What terminology accurately describes the result? Avoid “guaranteed” unless the design guarantees inclusion even when normal budgets are exceeded or explicitly reserves capacity. ### 3. Budget allocation and ordering Define behavior when applicable items exceed limits. Questions: - Do global, overridden, targeted, prioritized, and ranked items share one budget? - Should any category have a reserved sub-budget? - Can one category starve all lower-priority categories? - Should narrower contextual matches outrank broader matches? - Should recency influence ordering? - How are equal scores resolved deterministically? - Is the item limit applied before or after token estimation? - What happens when one item individually exceeds the token budget? The outcome must be deterministic, testable, and explainable. ### 4. Consumer-specific overrides Review the meaning and precedence of: - Default selection. - Explicit inclusion. - Explicit exclusion. - Consumer opt-out. - Global context. - Contextual targeting. - Future item-level priority. Define a precedence order and identify whether an override may bypass contextual mismatches, publication status, entity access, or configured limits. Access checks and publication status must not be bypassed by an inclusion priority. ### 5. Boundaries and exclusions Coordinate with #3586197. Questions: - Should exclusion be expressed through scope polarity, consumer overrides, or a separate constraint system? - Does a negative contextual match veto all positive ranking signals? - How should “None,” “Include,” and “Exclude” interact with an item-level priority? - Can the design support exclusion without reworking storage and forms again? ### 6. Selection explainability Determine what users need to understand selection results. Possible outputs include: - A preview for a selected consumer and context. - Reasons an item was applicable or inapplicable. - Scope matches and mismatches. - Subscription score. - Priority category. - Inclusion or exclusion override. - Item-limit or token-limit trimming. - Final ordering. - Debug logs or integration with AI debugging tools. Consider whether explainability is required before introducing additional priority controls. ### 7. Terminology and UX Validate terminology with UX review. Potential terms include: - Applicable - Eligible - Prioritized - Preferred - Included - Selected - Trimmed - Excluded - Context filter - Categorization - Environmental context The UI must not promise behavior that limits can invalidate. If scope roles are introduced in the API, that does not necessarily mean the same technical labels should appear in the user interface. ### 8. Backward compatibility and migration If behavior changes are recommended, identify: - Existing context item data that requires migration. - Existing consumer subscriptions affected by new semantics. - Defaults for existing and newly created items. - Treatment of existing Target entity items. - Configuration schema changes. - Scope index rebuild requirements. - Update-hook scalability and resumability. - API compatibility for custom scope plugins. - Deprecation and change-record requirements. A behavioral migration must not silently make previously selected context unavailable without an explicit decision and documented upgrade path. ### 9. Performance Evaluate: - Candidate-query and scope-index impact. - Additional entity loads. - Repeated contextual matching. - Token-estimation cost. - Selection-preview cost. - Cacheability of contextual values. - Update-hook behavior on large catalogs. Any proposed model should preserve indexed candidate selection where practical. ### 10. Accessibility If the proposal changes scope or priority forms, verify: - Controls have clear labels and descriptions. - Related controls use appropriate fieldsets and legends. - Status and limit feedback is not conveyed by color alone. - Dynamic changes are announced. - Keyboard and screen-reader users can understand priority and precedence. - Help text remains associated with the relevant controls. ## Options to compare The discussion should compare at least these high-level options: ### Option A: Documentation and explainability only Keep current selection behavior. Improve documentation, limit feedback, and selection diagnostics. ### Option B: Explicit scope roles only Add stable plugin metadata or capabilities for categorization and contextual behavior, without adding item-level priority. ### Option C: Item-level priority only Keep scope behavior unchanged but let item authors request stronger priority when the item is otherwise applicable. ### Option D: Scope roles and item-level priority Introduce both concepts as one coordinated model. ### Option E: Replace priority buckets with weighted ranking Express scope matches, item importance, consumer preferences, and contextual specificity through a unified scoring model. Other options may be added after the post-1.0 audit. ## Evaluation criteria Compare proposals using: - User comprehension. - Predictability. - Extensibility. - Backward compatibility. - Migration risk. - Performance. - Explainability. - Testability. - Accessibility. - Custom-plugin compatibility. - Suitability for multiple context consumers. - Interaction with exclusions and boundaries. - Implementation and maintenance complexity. ## Expected outcomes This discussion should produce: 1. A current-state selection diagram based on post-1.0 code. 2. A list of validated user problems. 3. A comparison of viable options and trade-offs. 4. A recommended scope and inclusion model, or a decision to retain the existing model. 5. Defined precedence and budget behavior if changes are recommended. 6. Agreed user-facing terminology. 7. Compatibility and migration requirements. 8. A list of focused implementation, documentation, test, and change-record issues. ## Non-goals This discussion does not: - Implement a scope type enum. - Add capability methods. - Change selection or scoring. - Add an item inclusion field. - Change forms or documentation. - Migrate subscriptions or context items. - Implement boundaries or exclusions. - Implement selection preview. - Commit to the earlier #3586281 API proposal. Implementation should begin only after the discussion records an agreed model. ## Acceptance criteria - [ ] The final post-1.0 scope and selection pipeline is documented. - [ ] Remaining user problems are supported by concrete examples or feedback. - [ ] Existing capability signals and extension points are inventoried. - [ ] At least options A–E are compared, or omitted options are explained. - [ ] Scope-role requirements are decided. - [ ] The need for item-level priority is decided. - [ ] Priority and override precedence is defined if changes are recommended. - [ ] Item and token budget behavior is defined if changes are recommended. - [ ] Target entity and Global behavior are addressed. - [ ] Boundaries and exclusions are considered. - [ ] Context-consumer architecture is considered. - [ ] Explainability requirements are decided. - [ ] UX terminology receives review. - [ ] Performance, accessibility, access, and migration risks are documented. - [ ] The discussion concludes with either a no-change decision or focused implementation follow-ups. ## Related issues - #3586281+s — beta-era scope roles and inclusion semantics proposal - #3586243+s — scope plugin persistence and capability API - #3586197+s — boundaries and exclusions - #3586270+s — scope-selection beta feedback - #3586335+s — UX decision to retain subscription terminology - #3586337+s — subscription-limit indicator - #3586348+s - clarify scope eligibility, ranking, and limits - #3586346+s — context-consumer architecture ## AI usage - [x] AI assisted issue