repo-scoping/workplans/RREG-WP-0005-scope-md-generation-feature.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-0005	workplan	SCOPE.md Generation Feature	capabilities	repo-registry	done	codex	foerster-capabilities	2026-04-30	2026-04-30	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

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

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

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

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

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:

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]

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.