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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RREG-WP-0012	workplan	Activity-Core Scope Context API	capabilities	repo-scoping	active	codex	foerster-capabilities	2026-05-14	2026-05-15	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:

GET /repos/{repo_slug}/scope/context

The endpoint returns application/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

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

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

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

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.