generated from coulomb/repo-seed
179 lines
6.8 KiB
Markdown
179 lines
6.8 KiB
Markdown
---
|
|
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.
|