the-custodian/workplans/CUST-WP-0034-scope-md-delegation-prep.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
CUST-WP-0034	workplan	SCOPE.md Delegation — Custodian Preparation	custodian	the-custodian	todo	custodian	custodian	2026-04-30	2026-04-30	bf94b5e9-2bc3-4c09-88cd-233849d4d86c

CUST-WP-0034 — SCOPE.md Delegation Preparation

Goal

Prepare the custodian to delegate SCOPE.md generation and maintenance to repo-scoping. Three concrete changes: (1) upgrade the DOI engine's C5 check from file-presence to content-structure validation so the custodian can detect stale or non-conforming SCOPE.md files; (2) register a capability request route so "scope.generate" and "scope.update" requests are formally routed to repo-scoping; (3) update the scope-analyst kaizen agent to describe itself as a routing shim rather than a standalone analyser.

This workplan does not move any SCOPE.md generation logic — that lives in RREG-WP-0005. It only makes the custodian aware of the delegation interface.

Depends on: none
Unblocks: RREG-WP-0005 (capability route must exist before registration), RREG-WP-0006

T01: Upgrade DOI engine C5 — content structure validation

id: CUST-WP-0034-T01
status: todo
priority: high
state_hub_task_id: "7d31bbea-cebf-486e-b622-05bc5ca141ea"

Replace the current file-presence check in state-hub/api/doi_engine.py (C5) with a three-level content check:

• C5a (pass/fail): SCOPE.md present at repo root
• C5b (pass/warn): All 11 standard sections present as H2 headings: One-liner, Core Idea, In Scope, Out of Scope, Relevant When, Not Relevant When, Current State, How It Fits, Terminology, Related / Overlapping, Provided Capabilities
• C5c (pass/warn): ## Provided Capabilities contains at least one fenced capability block that parses as valid YAML with type and title

C5b and C5c emit warn (not fail) so a stub SCOPE.md doesn't hard-fail the DoI gate while still surfacing clearly in the dashboard.

Acceptance: make check-doi REPO=the-custodian reports C5a/C5b/C5c separately; the-custodian SCOPE.md passes all three; a repo with a blank stub SCOPE.md shows C5b and C5c as warn.

T02: Surface SCOPE.md health in repo dispatch

id: CUST-WP-0034-T02
status: todo
priority: medium
state_hub_task_id: "243280c7-3e68-4791-9243-ef9ee6b6d311"

Extend GET /repos/{slug}/dispatch with a scope_needs_review: bool field. It is true when either C5b or C5c is warn or fail for the repo. This ensures agents picking up a repo at session start see the signal without needing to call the DOI engine separately.

Also add scope_needs_review to the MCP get_repo_dispatch tool output.

Acceptance: for a repo with a stub SCOPE.md, get_repo_dispatch("that-repo") returns scope_needs_review: true; for a repo with a valid SCOPE.md it returns false.

T03: Register capability routes for scope generation

id: CUST-WP-0034-T03
status: todo
priority: high
state_hub_task_id: "042c54d4-0aa6-41e1-9497-4172986d779b"

Register two capability routes in the custodian's capability request system pointing to repo-scoping:

capability_key: scope.generate
provider_repo: repo-scoping
description: >
  Generate a SCOPE.md from scratch for a given repo using its approved
  characteristics profile.
input_schema: {repo_slug: string, output_path: string}

capability_key: scope.update
provider_repo: repo-scoping
description: >
  Diff an existing SCOPE.md against the current characteristics profile
  and write an updated version.
input_schema: {repo_slug: string, output_path: string}

Use register_capability() (MCP tool) or the /capabilities/ API directly. These routes are the formal contract that downstream automation (and the scope-analyst agent) will use to trigger SCOPE.md work.

Acceptance: list_capabilities() returns both scope.generate and scope.update with provider_repo: repo-scoping.

T04: Update scope-analyst kaizen agent

id: CUST-WP-0034-T04
status: todo
priority: medium
state_hub_task_id: "b6d64844-8a6d-4856-bdf5-3867fb49f215"

Update agents/agent-scope-analyst.md:

1. Add a short Delegation section at the top explaining that as of RREG-WP-0005, the authoritative SCOPE.md generator is repo-scoping. The scope-analyst persona is now a routing shim: it inspects the repo, decides whether scope.generate or scope.update is appropriate, and issues the capability request via request_capability().

2. Retain the existing heuristics and template sections — they remain valid as the spec that repo-scoping must produce to. They also serve as fallback if repo-scoping is unavailable.

3. Add a code example showing how to issue the capability request:

   request_capability(
     capability_key="scope.generate",
     requesting_repo="the-custodian",
     payload={"repo_slug": "target-repo", "output_path": "/path/to/SCOPE.md"}
   )
   

Acceptance: get_kaizen_agent("scope-analyst") returns the updated persona; the delegation flow is clear in the first screen of the agent instructions.