From a5021091443291e081c6a512c5f92e288f4de3a9 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 14 May 2026 18:12:36 +0200 Subject: [PATCH] chore(workplan): stub RREG-WP-0012 activity-core context API Workplan for stabilising the GET /repos/{slug}/scope endpoint as a formal contract for activity-core's RepoScopingContextResolver. Covers schema definition, scope_md_exists field, and provider-side contract test. Hub workstream: 83a43ab6-d566-41e0-afd7-f2833812564f Co-Authored-By: Claude Sonnet 4.6 --- .../RREG-WP-0012-activity-core-context-api.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 workplans/RREG-WP-0012-activity-core-context-api.md diff --git a/workplans/RREG-WP-0012-activity-core-context-api.md b/workplans/RREG-WP-0012-activity-core-context-api.md new file mode 100644 index 0000000..3ebfeca --- /dev/null +++ b/workplans/RREG-WP-0012-activity-core-context-api.md @@ -0,0 +1,152 @@ +--- +id: RREG-WP-0012 +type: workplan +domain: custodian +repo: repo-scoping +status: active +state_hub_workstream_id: 83a43ab6-d566-41e0-afd7-f2833812564f +tasks: + - id: T01 + title: Define context query response schema for activity-core + state_hub_task_id: 83482f1d-4f44-440d-a27f-0c375786b87f + status: todo + - id: T02 + title: Verify/implement GET /repos/{slug}/scope endpoint + state_hub_task_id: 75f6123a-2703-42ec-9564-dd665e16c5ef + status: todo + - id: T03 + title: Add scope_md_exists boolean to scope response + state_hub_task_id: cb0b17f4-30c4-4d68-b2ff-9a3fa9ef73a3 + status: todo + - id: T04 + title: Write integration test for activity-core repo-scoping adapter + state_hub_task_id: f70c1c58-b23f-4b61-adca-a02644b6ee7e + status: todo +created: "2026-05-14" +--- + +# RREG-WP-0012: Activity-Core Context API + +## Purpose + +activity-core's `RunActivityWorkflow` resolves context before evaluating rules +and instructions. One of its context sources is repo-scoping: given a repo slug, +it queries repo-scoping for the repo's capability profile (tags, capabilities, +whether a SCOPE.md exists, etc.). + +This workplan ensures repo-scoping exposes a stable, documented context API +endpoint that activity-core can call reliably. It is a **contract workplan** — +the goal is a stable interface, not new functionality. + +## Context + +- **activity-core WP-0003** (in progress): implements `RepoScopingContextResolver` + in `src/activity_core/context_resolvers/repo_scoping.py` which calls + `GET /repos/{slug}/scope` on the repo-scoping API. +- **repo-scoping** already has a scope API; the question is whether it returns + the exact fields activity-core needs, and whether those fields are stable. + +See: `docs/adr/adr-001-event-bridge-architecture.md` in activity-core, section +on context resolution adapters. + +## Scope + +**In scope:** +- Documenting and stabilizing the `/repos/{slug}/scope` endpoint response schema +- Adding `scope_md_exists` if not present +- Contract/integration test + +**Out of scope:** +- Dynamic operational state (that is the state hub's domain, not repo-scoping's) +- NATS-based context queries (REST only for now) +- Any new scope analysis features + +## Contract + +The endpoint `GET /repos/{slug}/scope` must return: + +```json +{ + "repo_slug": "string", + "capabilities": ["string"], + "tags": ["string"], + "scope_md_exists": true, + "scope_summary": "string or null" +} +``` + +| Field | Type | Required | Notes | +|---|---|---|---| +| `repo_slug` | string | yes | URL-safe identifier | +| `capabilities` | string[] | yes | Declared capability types | +| `tags` | string[] | yes | Free-form classification tags | +| `scope_md_exists` | boolean | yes | True if SCOPE.md present in repo root | +| `scope_summary` | string or null | no | First paragraph of SCOPE.md if present | + +This schema is the contract. Changes must be versioned and communicated to the +activity-core agent before deployment. + +## Tasks + +### T01 — Define context query response schema for activity-core + +Write a JSON Schema file (`docs/schemas/repo-scope-context-response.json`) that +formalizes the response shape above. Include field descriptions and examples. +This becomes the machine-readable contract between repo-scoping and activity-core. + +### T02 — Verify/implement GET /repos/{slug}/scope endpoint + +Check the existing API for `GET /repos/{slug}/scope`. Verify it returns all +required fields. If missing fields, implement them. If the endpoint does not +exist, implement it. + +The endpoint is called by activity-core's `RepoScopingContextResolver` and +must be stable — no breaking changes without coordinating with activity-core. + +### T03 — Add scope_md_exists boolean to scope response + +Ensure `scope_md_exists` is present and accurate: `true` if a `SCOPE.md` file +exists in the repo's root directory on the default branch, `false` otherwise. + +This field is used by activity-core rules to decide whether to emit a +generate-SCOPE.md task for a repo. + +### T04 — Write integration test for activity-core repo-scoping adapter + +Write a contract test that: +1. Calls `GET /repos/{slug}/scope` with a known test repo slug +2. Asserts all required fields are present +3. Asserts types match the schema (scope_md_exists is bool, capabilities is list, etc.) + +This test lives in repo-scoping as the provider-side contract test. It should +run in CI so contract drift is caught before it breaks activity-core. + +**Test file**: `tests/test_scope_context_api.py` (or alongside existing API tests) + +## Build Order + +``` +T01 (schema) → T02 (implement) → T03 (add field) → T04 (test) +``` + +## Completion Criteria + +1. `GET /repos/{slug}/scope` returns all five required fields +2. `scope_md_exists` is accurate for at least three test repos +3. JSON Schema file committed to `docs/schemas/` +4. Contract test passes in CI +5. activity-core agent confirmed the `RepoScopingContextResolver` integration works + +## Notes + +- The local agent implementing this should coordinate with the activity-core agent + to confirm the exact field names and types before implementing T02. +- Do **not** add dynamic operational state to this endpoint (e.g., last_commit_at, + open_issues_count) — that belongs to the state hub context adapter, not repo-scoping. +- `scope_summary` is optional (null OK) — do not block on extracting it if the + SCOPE.md parsing is complex. + +## Change History + +- v0.1 (2026-05-14): Stub created by activity-core agent during WP-0003 planning. + Local agent to flesh out and implement.