---
id: RREG-WP-0012
type: workplan
title: "Activity-Core Scope Context API"
domain: capabilities
repo: repo-scoping
status: active
owner: codex
topic_slug: foerster-capabilities
created: "2026-05-14"
updated: "2026-05-15"
state_hub_workstream_id: "83a43ab6-d566-41e0-afd7-f2833812564f"
---

# Activity-Core Scope Context API

activity-core's `RunActivityWorkflow` resolves repository context before
evaluating rules and instructions. One of its context sources is repo-scoping:
given a repo slug, activity-core needs a compact capability profile with
capability names, classification tags, whether a `SCOPE.md` is known to exist,
and a short scope summary when available.

This is a contract workplan. The goal is a stable JSON interface for
activity-core, not new scope analysis functionality.

## Contract Decision

Do not change `GET /repos/{repo_slug}/scope`. That endpoint already exists as
the generated `SCOPE.md` Markdown preview endpoint, with sibling diff/write
routes. Changing its success media type or response shape would break existing
repo-scoping API clients and the OpenAPI contract policy.

Add a new provider-side context endpoint instead:

```text
GET /repos/{repo_slug}/scope/context
```

The endpoint returns `application/json`:

```json
{
  "repo_slug": "repo-scoping",
  "capabilities": ["Generate SCOPE.md"],
  "tags": ["api", "generation", "scope"],
  "scope_md_exists": true,
  "scope_summary": "Repository Scoping maps repositories into reviewable scope graphs."
}
```

| Field | Type | Required | Source |
|---|---|---|---|
| `repo_slug` | string | yes | Slug requested by the caller after normal slugification |
| `capabilities` | string[] | yes | Approved capability names from the repository ability map |
| `tags` | string[] | yes | Stable, sorted union of approved ability and capability `primary_class` values plus their `attributes` |
| `scope_md_exists` | boolean | yes | True when repo-scoping can inspect a local or cached checkout and root `SCOPE.md` exists; false when absent or unknown |
| `scope_summary` | string or null | yes | First non-empty paragraph of root `SCOPE.md` when inspectable; otherwise approved scope description, repository description, or null |

The `scope_md_exists` field is intentionally conservative. The provider must
not clone or fetch remote repositories merely to answer this lightweight context
query. If no local or cached checkout is available, the value is `false` and
`scope_summary` falls back to registry metadata.

activity-core should call this new endpoint, not the Markdown preview endpoint.
If a future contract needs an unknown/absent distinction for `SCOPE.md`, add a
new optional field such as `scope_md_status` rather than changing the boolean.

## T01: Define Context Query Response Schema

```task
id: RREG-WP-0012-T01
status: done
priority: high
state_hub_task_id: "83482f1d-4f44-440d-a27f-0c375786b87f"
```

Write `docs/schemas/repo-scope-context-response.json` to formalize the response
shape above. Include field descriptions, required fields, `additionalProperties:
false`, and at least one complete example.

Acceptance criteria:
- The schema describes `repo_slug`, `capabilities`, `tags`, `scope_md_exists`,
  and `scope_summary`.
- Required fields match the contract table.
- The schema is easy for activity-core to vendor or validate against.

## T02: Implement Scope Context Endpoint

```task
id: RREG-WP-0012-T02
status: done
priority: high
state_hub_task_id: "75f6123a-2703-42ec-9564-dd665e16c5ef"
```

Implement `GET /repos/{repo_slug}/scope/context` in repo-scoping. The endpoint
must return the JSON contract above and must preserve the existing
`GET /repos/{repo_slug}/scope` Markdown behavior.

Acceptance criteria:
- The endpoint resolves repositories with the same slug rules as the existing
  scope endpoints.
- Repositories without approved capabilities still return a valid context
  response with empty `capabilities` and `tags`.
- Missing repository slugs return the existing `404` error shape.
- The OpenAPI snapshot includes the new endpoint and response model.

## T03: Resolve SCOPE.md Presence And Summary

```task
id: RREG-WP-0012-T03
status: done
priority: high
state_hub_task_id: "cb0b17f4-30c4-4d68-b2ff-9a3fa9ef73a3"
```

Populate `scope_md_exists` and `scope_summary` without performing network
operations. Reuse local source paths, cached checkouts, and State Hub local path
lookup where available.

Acceptance criteria:
- A local registered repo with root `SCOPE.md` returns `scope_md_exists: true`.
- A local registered repo without root `SCOPE.md` returns `scope_md_exists:
  false`.
- A remote repo with no cached checkout returns `scope_md_exists: false` and a
  metadata fallback summary when available.
- `scope_summary` extracts the first non-empty paragraph after headings or
  frontmatter noise when a `SCOPE.md` file is inspectable.

## T04: Add Provider-Side Contract Tests

```task
id: RREG-WP-0012-T04
status: done
priority: high
state_hub_task_id: "f70c1c58-b23f-4b61-adca-a02644b6ee7e"
```

Add `tests/test_scope_context_api.py` or equivalent focused API coverage for
the new context endpoint.

Acceptance criteria:
- Tests assert all required fields and types.
- Tests cover at least three repository cases: local with `SCOPE.md`, local
  without `SCOPE.md`, and remote/uncached.
- Tests assert the existing Markdown `/scope` endpoint still returns Markdown.
- Tests assert the OpenAPI contract exposes the new response model.

## Completion Criteria

- `GET /repos/{repo_slug}/scope/context` returns the five-field JSON contract.
- Existing `GET /repos/{repo_slug}/scope` Markdown preview behavior is unchanged.
- `docs/schemas/repo-scope-context-response.json` exists.
- Provider-side contract tests pass in CI.
- activity-core updates `RepoScopingContextResolver` to call `/scope/context`.

Implementation note 2026-05-15: repo-scoping provider work is complete. Added
`GET /repos/{repo_slug}/scope/context`, the Pydantic response model, the JSON
Schema artifact, focused provider-side contract tests, and OpenAPI snapshot
coverage. Full repo test suite passed locally with `.venv/bin/python -m pytest`
(`140 passed`). Workplan remains active until activity-core updates and confirms
its resolver.

## Notes

- Dynamic operational state such as last commit time, open issues, active tasks,
  or runtime health belongs to the State Hub context adapter, not this endpoint.
- This endpoint should be cheap and deterministic. It must not trigger scans,
  clones, LLM calls, or SCOPE.md generation.
- Backward-compatible additions can be optional fields. Required field changes
  need coordination with activity-core.

## Change History

- v0.1 (2026-05-14): Stub created by activity-core agent during WP-0003 planning.
- v0.2 (2026-05-15): Revised by repo-scoping agent to avoid breaking the
  existing Markdown `/scope` endpoint, define `/scope/context`, and normalize
  ADR-001 task blocks.