the-custodian/workplans/archived/260501-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	done	custodian	custodian	2026-04-30	2026-05-01	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

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

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

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

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

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.