repo-scoping/workplans/RREG-WP-0012-activity-core-context-api.md

id, type, domain, repo, status, state_hub_workstream_id, tasks, created

id	type	domain	repo	status	state_hub_workstream_id	tasks	created
RREG-WP-0012	workplan	custodian	repo-scoping	active	83a43ab6-d566-41e0-afd7-f2833812564f	id title state_hub_task_id status T01 Define context query response schema for activity-core 83482f1d-4f44-440d-a27f-0c375786b87f todo id title state_hub_task_id status T02 Verify/implement GET /repos/{slug}/scope endpoint 75f6123a-2703-42ec-9564-dd665e16c5ef todo id title state_hub_task_id status T03 Add scope_md_exists boolean to scope response cb0b17f4-30c4-4d68-b2ff-9a3fa9ef73a3 todo id title state_hub_task_id status T04 Write integration test for activity-core repo-scoping adapter f70c1c58-b23f-4b61-adca-a02644b6ee7e todo	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:

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