repo-scoping/workplans/RREG-WP-0005-scope-md-generation-feature.md

---
id: RREG-WP-0005
type: workplan
title: "SCOPE.md Generation Feature"
domain: capabilities
repo: repo-registry
status: done
owner: codex
topic_slug: foerster-capabilities
created: "2026-04-30"
updated: "2026-04-30"
state_hub_workstream_id: "5da7ddd9-b192-4271-ba86-c5365405a685"
---

# RREG-WP-0005 — SCOPE.md Generation Feature

## Goal

Implement SCOPE.md generation and structured update as a first-class output
capability of repo-registry. SCOPE.md is the human- and agent-facing entry
point to a repository's utility story. Its sections map directly onto the
characteristics hierarchy (Scope → Ability → Capability → Feature → Observed
Facts with Evidence), so repo-registry — which already holds this data for
analysed repos — is the natural producer.

This workplan: (1) establishes the SCOPE.md reference spec inside repo-registry
as the definitive document; (2) builds a generator that maps approved
characteristics to SCOPE.md sections; (3) builds a validator/differ so stale
files can be detected; (4) exposes the feature via API endpoints and (5)
registers the `scope.generate` and `scope.update` capabilities in the custodian
so routing can find them.

Depends on: RREG-WP-0004 (classification model must be in place)  
Unblocks: RREG-WP-0006

## T01: Own the SCOPE.md reference specification

```task
id: RREG-WP-0005-T01
status: done
priority: high
state_hub_task_id: "83154aae-dd06-4329-8df6-3906b2bf0f14"
```

Port `state-hub/dashboard/src/docs/scope.md` from the-custodian into
`repo-registry/docs/scope-md-spec.md` and upgrade it to reflect the full
characteristics hierarchy.

Key changes to the spec:
- Map each of the 11 sections to its source in the characteristics model:
  - **One-liner / Core Idea** ← Scope characteristic text
  - **In Scope / Out of Scope** ← Ability-level characteristics (what the
    repo enables vs. what is explicitly absent)
  - **Relevant When / Not Relevant When** ← Feature-level characteristics
    with primary_class `business-usecase`
  - **Current State** ← Observed Facts aggregated by scanner
  - **How It Fits** ← Support/evidence references between characteristics and
    other repos
  - **Terminology** ← Domain term facts extracted by scanner or LLM
  - **Related / Overlapping** ← Cross-repo support references
  - **Provided Capabilities** ← Capability characteristics (machine-readable
    blocks, format unchanged from existing spec)
- Document what sections are auto-generated vs. curator-owned (require human
  review before writing)
- Cross-reference `docs/characteristic-evidence-model.md` and
  `docs/classification-strategy.md`

Coordinate with the-custodian: once this spec is stable, the copy at
`state-hub/dashboard/src/docs/scope.md` should redirect here as the source
of truth (or be removed in RREG-WP-0006).

Acceptance: `docs/scope-md-spec.md` exists, covers all 11 sections with
explicit characteristic-to-section mappings, and is consistent with the
existing template at `state-hub/scripts/project_rules/scope.template`.

Implementation note 2026-04-30: `docs/scope-md-spec.md` now owns the reference
specification. It maps the current Custodian template headings to the
Scope/Ability/Capability/Feature/Evidence/Facts model, documents generated vs.
curator-owned sections, preserves the existing capability block format, and
cross-references the characteristic/evidence and classification strategy docs.

## T02: Build SCOPE.md generator

```task
id: RREG-WP-0005-T02
status: done
priority: high
state_hub_task_id: "39feb7ea-72ca-4d99-8094-b006df605dbe"
```

New module `src/repo_registry/scope/generator.py`.

Given a repo slug with approved characteristics, produce a SCOPE.md string:

1. **Retrieve** approved characteristics from DB: scope (root), abilities,
   capabilities, features, facts, support references
2. **Map** each section following the spec from T01:
   - Pull scope characteristic title/description → one-liner and core idea
   - Pull abilities with primary_class grouping → in/out-of-scope bullets
   - Pull features with `business-usecase` primary_class → relevant-when bullets
   - Pull scanner-produced facts (language, framework, route count, etc.) →
     current state indicators
   - Pull inter-repo support references → how-it-fits and related sections
   - Pull capability characteristics → `## Provided Capabilities` blocks
     (emit in the existing `capability` block YAML format)
3. **Render** to Markdown with the exact 11-section structure

Sections for which no characteristics data exists should render as stubs
with a `<!-- needs curator input -->` comment so they are obvious in review.

Expose as `ScopeGenerator.generate(repo_slug: str) -> str`.

Acceptance: calling `ScopeGenerator.generate("repo-registry")` produces a
valid SCOPE.md; all 11 sections are present; the `## Provided Capabilities`
section contains parseable capability blocks; the output passes the C5b/C5c
checks defined in CUST-WP-0034-T01.

Implementation note 2026-04-30: `repo_registry.scope.ScopeGenerator` now renders
SCOPE.md from approved repository scope, abilities, capabilities, features, facts,
support evidence, and classification metadata. It preserves the current template
headings, emits curator-input stubs for missing data, and renders approved
capabilities as parseable `capability` blocks.

## T03: Build SCOPE.md validator and differ

```task
id: RREG-WP-0005-T03
status: done
priority: high
state_hub_task_id: "0c9c1347-368a-4657-a039-ae143a6500bd"
```

New module `src/repo_registry/scope/validator.py`.

`ScopeValidator.diff(repo_slug: str, existing_path: Path) -> ScopeDiff`:
- Parse existing SCOPE.md sections
- Generate fresh content via `ScopeGenerator`
- Produce a structured diff: `{section: str, status: "ok"|"stale"|"missing",
  current_text: str|None, proposed_text: str|None}`
- A section is `stale` if the current text differs materially from generated
  content (use normalized whitespace and stripped Markdown for comparison)
- A section is `missing` if the heading does not appear at all

`ScopeValidator.validate(path: Path) -> ValidationResult`:
- Check C5a/C5b/C5c rules (mirrors doi_engine logic; no DB needed)
- Return list of issues: `{check: str, severity: "error"|"warn", message: str}`

Acceptance: `ScopeValidator.diff("repo-registry", Path("SCOPE.md"))` returns
a diff with at least some `ok` sections and surfaces any real gaps; the
validator catches a missing `## Provided Capabilities` section as a `warn`.

Implementation note 2026-04-30: `repo_registry.scope.ScopeValidator` now validates
C5a/C5b/C5c-style SCOPE.md structure, parses capability blocks, and produces
section-aware diffs against freshly generated content.

## T04: API endpoints

```task
id: RREG-WP-0005-T04
status: done
priority: high
state_hub_task_id: "a2d1937b-f9e2-480e-8e28-1c12837e1b23"
```

Add three endpoints under `/repos/{slug}/scope/`:

- `GET /repos/{slug}/scope` — generate SCOPE.md from current approved
  characteristics and return as `text/plain` (dry-run, does not write to disk)
- `POST /repos/{slug}/scope/write` — generate and write to the repo's local
  path (uses `host_paths` from managed_repos, same pattern as
  `consistency_check.py`); returns `{written: true, path: str}`
- `GET /repos/{slug}/scope/diff` — return JSON `ScopeDiff` comparing current
  file on disk to generated content; returns `{sections: [...], needs_update: bool}`

All endpoints 404 if the repo slug is not registered or has no approved
characteristics. `/scope/write` 409 if the repo has no known local path on
the current host.

Acceptance: `GET /repos/repo-registry/scope` returns valid Markdown; `GET
/repos/repo-registry/scope/diff` returns a diff JSON; a `POST` write succeeds
and the written file passes the validator.

Implementation note 2026-04-30: Added `/repos/{repo_slug}/scope`,
`/repos/{repo_slug}/scope/diff`, and `/repos/{repo_slug}/scope/write` API
endpoints. The endpoints resolve registered repositories by slug, require
approved characteristics, use a local repository path or cached checkout for
diff/write operations, and return 409 when no local path is available.

## T05: Register capabilities in custodian

```task
id: RREG-WP-0005-T05
status: done
priority: medium
state_hub_task_id: "e1bd4a4f-3d9a-4384-a254-ef75bd9905b9"
```

Add two capability blocks to `SCOPE.md` under `## Provided Capabilities`:

```capability
type: api
title: scope.generate
description: >
  Generates a SCOPE.md from scratch for a registered repo using its approved
  characteristics profile (abilities, capabilities, features, facts).
keywords: [scope, scope-md, generation, repository-utility]
```

```capability
type: api
title: scope.update
description: >
  Diffs an existing SCOPE.md against the current characteristics profile
  and returns or writes an updated version.
keywords: [scope, scope-md, update, diff, staleness]
```

Then run `make ingest-capabilities REPO=repo-registry` (from the-custodian)
so the custodian's capability catalog picks them up. The routes registered in
CUST-WP-0034-T03 will then resolve correctly.

Acceptance: `list_capabilities()` in the state-hub MCP returns `scope.generate`
and `scope.update` with `provider_repo: repo-registry`; `request_capability`
with either key resolves without routing error.

Implementation note 2026-04-30: Added `scope.generate` and `scope.update`
capability blocks to `SCOPE.md`, then ingested them with the State Hub
capability ingestion script using `/home/worsch/repo-registry` as the explicit
repo path. The State Hub catalog created `api/scope.generate` and
`api/scope.update` entries for `repo-registry`.