---
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.