the-custodian/workplans/CUST-WP-0034-scope-md-delegation-prep.md

---
id: CUST-WP-0034
type: workplan
title: "SCOPE.md Delegation — Custodian Preparation"
domain: custodian
repo: the-custodian
status: done
owner: custodian
topic_slug: custodian
created: "2026-04-30"
updated: "2026-05-01"
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. The work now has four 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) surface
structured SCOPE.md health in repo dispatch and ecosystem refresh queries;
(3) register capability request routes so `scope.generate` and `scope.update`
requests are formally routed to repo-scoping; (4) 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: done
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: done
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`.

Completed in the same implementation pass as T05. Dispatch now also includes
`scope_issue_details`.

## T03: Register capability routes for scope generation

```task
id: CUST-WP-0034-T03
status: done
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`.

Completed: State Hub capability catalog contains active `scope.generate` and
`scope.update` entries attributed to `repo-scoping`.

## T04: Update scope-analyst kaizen agent

```task
id: CUST-WP-0034-T04
status: done
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(
     title="scope.generate",
     description="Generate SCOPE.md for target-repo at /path/to/SCOPE.md",
     capability_type="api",
     requesting_agent="scope-analyst",
     requesting_domain="custodian",
     requesting_workstream_id="<workstream-uuid>",
     priority="medium",
   )
   ```

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

Completed: `agents/agent-scope-analyst.md` now opens with the delegation model,
uses repo-scoping as the authoritative generator/updater, and includes a
`request_capability(...)` example matching the live State Hub MCP signature.

## T05: Expose structured SCOPE.md health for repo-scoping refresh

```task
id: CUST-WP-0034-T05
status: done
priority: high
assignee: custodian
state_hub_task_id: "b5d5a1f2-4148-4a1e-86e0-2249f6d633cc"
```

Unblock repo-scoping RREG-WP-0006-T04 by making State Hub's SCOPE.md health
machine-readable enough for ecosystem-wide refresh.

Implemented State Hub support:

- Split DoI C5 into C5a file presence, C5b canonical section structure, and
  C5c capability block parseability.
- Exposed `scope_needs_review` and `scope_issue_details` from
  `GET /repos/{slug}/dispatch`; the MCP `get_repo_dispatch` tool inherits the
  same JSON shape.
- Added `GET /repos/scope-health?needs_review=true&reachable_only=true` so
  repo-scoping can request the exact reachable repos needing SCOPE.md
  generation/update.
- Included reason codes and targeted refresh hints:
  `missing_sections`, `invalid_capability_blocks`, and
  `needs_refresh_sections`.
- Documented the contract in `state-hub/mcp_server/TOOLS.md`.

Acceptance: repo-scoping can call State Hub and get a complete list of
reachable repos needing SCOPE.md generation/update, with reason codes for
missing file, missing/stale sections, and missing/invalid capability
declarations.

Verification:

- `state-hub/.venv/bin/python -m pytest tests/test_doi_scope_health.py -q`
  passed: 5 tests.
- `state-hub/.venv/bin/python -m pytest -x -q` passed: 228 tests.
- `git diff --check` passed.