Skip to content

feat(context): scenario taxonomy and request/response contract for adr_planning_context#21

Merged
kschlt merged 2 commits into
mainfrom
feat/context-projection-api
Apr 4, 2026
Merged

feat(context): scenario taxonomy and request/response contract for adr_planning_context#21
kschlt merged 2 commits into
mainfrom
feat/context-projection-api

Conversation

@kschlt
Copy link
Copy Markdown
Owner

@kschlt kschlt commented Apr 4, 2026

Why

The adr_planning_context MCP tool currently accepts a free-text context_type field, which gives callers no structured way to express what kind of planning scenario they are in. This PR establishes the typed API layer — scenario enum, request model, and response packet — that the retrieval and rendering logic will build on in subsequent items.

Approach

Four named scenarios replace free-text context_type: new_adr, amend_existing, replace_supersede, and explore_options. Each maps to a projection of what context is relevant. The new ContextScenario, ChangeMode, and DetailLevel enums, combined with ContextRequest and ScenarioContextPacket Pydantic v2 models, form the contract hub. PlanningContextRequest gains five backward-compatible optional fields so no existing callers break — they continue working without changes. All ten new types are exported from the context package. The design favours progressive disclosure: callers can provide as little as a scenario name and get a useful response, or add scope hints and target refs for more precise projection.

What Was Tested

  • 41 new unit tests across two files: scenario enum resolution and projection logic coverage, and PlanningContextRequest backward-compatibility (all new fields optional with defaults, existing callers unaffected).
  • Full quality suite (ruff, mypy, black, 592 unit/integration tests) passes cleanly.

Risks

Downstream callers using a free-text context_type string will eventually need to migrate to one of the four named scenarios once retrieval logic starts consuming the enum. No breakage today — the field remains backward-compatible — but migration will be required before the enum-driven retrieval is enabled.

kschlt added 2 commits April 3, 2026 20:09
… for adr_planning_context

Establishes the API design layer for scenario-aware context retrieval — the
schema foundation that retrieval and rendering logic will build on. Introduces
ContextScenario (4 scenarios), ChangeMode, and DetailLevel enums; ScopeHint,
TargetRef, ContextRequest, ConstraintSummary, InspectReference, PacketMetadata,
and ScenarioContextPacket Pydantic v2 models in adr_kit/context/models.py.
Exports all 10 new types from the context package. Extends PlanningContextRequest
with 5 backward-compatible optional scenario fields so existing callers require
no changes. Validated by 41 new unit tests across two test files.
@kschlt kschlt merged commit e6d27ad into main Apr 4, 2026
8 checks passed
@kschlt kschlt deleted the feat/context-projection-api branch April 4, 2026 15:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant