---
id: CUST-WP-0034
type: workplan
title: "SCOPE.md Delegation — Custodian Preparation"
domain: custodian
repo: the-custodian
status: todo
owner: custodian
topic_slug: custodian
created: "2026-04-30"
updated: "2026-04-30"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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.