Delegation of scope functionality to repo-scoping completed

agents/agent-scope-analyst.md

@@ -5,11 +5,50 @@ category: project-management
 model: inherit
 ---
 
+# DELEGATION
+
+As of RREG-WP-0005 / CUST-WP-0034, the authoritative SCOPE.md generator and
+updater is the `repo-scoping` repository.
+
+This agent is now primarily a routing shim:
+
+- inspect the target repository enough to decide whether a new SCOPE.md is
+  needed or an existing one should be refreshed;
+- prefer `scope.generate` when no SCOPE.md exists or the file is only a stub;
+- prefer `scope.update` when a SCOPE.md exists but State Hub reports missing
+  sections, invalid capability blocks, or stale boundaries;
+- issue a State Hub capability request to route the work to `repo-scoping`;
+- use the heuristics and template below as the output contract and fallback
+  guidance if repo-scoping is unavailable.
+
+Example request:
+
+```python
+request_capability(
+    title="scope.generate",
+    description=(
+        "Generate SCOPE.md for target-repo at /path/to/target-repo/SCOPE.md "
+        "using the approved repository characteristics profile."
+    ),
+    capability_type="api",
+    requesting_agent="scope-analyst",
+    requesting_domain="custodian",
+    requesting_workstream_id="<workstream-uuid>",
+    priority="medium",
+)
+```
+
+For an existing file, use `title="scope.update"` and describe the specific
+State Hub `scope_issue_details`, especially `needs_refresh_sections`.
+
+---
+
 # ROLE
 
 You are a **Repository Scope Analyst**.
 
-Your task is to analyze a code repository and produce or improve a `SCOPE.md` file that helps humans and agents quickly understand:
+Your task is to analyze a code repository and route, produce, or improve a
+`SCOPE.md` file that helps humans and agents quickly understand:
 
 - what the repository is about
 - what capability it provides

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

@@ -4,11 +4,11 @@ type: workplan
 title: "SCOPE.md Delegation — Custodian Preparation"
 domain: custodian
 repo: the-custodian
-status: todo
+status: done
 owner: custodian
 topic_slug: custodian
 created: "2026-04-30"
-updated: "2026-04-30"
+updated: "2026-05-01"
 state_hub_workstream_id: "bf94b5e9-2bc3-4c09-88cd-233849d4d86c"
 ---
 
@@ -17,12 +17,14 @@ state_hub_workstream_id: "bf94b5e9-2bc3-4c09-88cd-233849d4d86c"
 ## Goal
 
 Prepare the custodian to delegate SCOPE.md generation and maintenance to
-repo-scoping. Three concrete changes: (1) upgrade the
+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) register
+the custodian can detect stale or non-conforming SCOPE.md files; (2) surface
-a capability request route so "scope.generate" and "scope.update" requests are
+structured SCOPE.md health in repo dispatch and ecosystem refresh queries;
-formally routed to repo-scoping; (3) update the scope-analyst kaizen agent to
+(3) register capability request routes so `scope.generate` and `scope.update`
-describe itself as a routing shim rather than a standalone analyser.
+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.
@@ -34,7 +36,7 @@ Unblocks: RREG-WP-0005 (capability route must exist before registration), RREG-W
 
 ```task
 id: CUST-WP-0034-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "7d31bbea-cebf-486e-b622-05bc5ca141ea"
 ```
@@ -61,7 +63,7 @@ stub SCOPE.md shows C5b and C5c as warn.
 
 ```task
 id: CUST-WP-0034-T02
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "243280c7-3e68-4791-9243-ef9ee6b6d311"
 ```
@@ -77,11 +79,14 @@ 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: todo
+status: done
 priority: high
 state_hub_task_id: "042c54d4-0aa6-41e1-9497-4172986d779b"
 ```
@@ -114,11 +119,14 @@ 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: todo
+status: done
 priority: medium
 state_hub_task_id: "b6d64844-8a6d-4856-bdf5-3867fb49f215"
 ```
@@ -138,11 +146,59 @@ Update `agents/agent-scope-analyst.md`:
 3. Add a code example showing how to issue the capability request:
    ```
    request_capability(
-     capability_key="scope.generate",
+     title="scope.generate",
-     requesting_repo="the-custodian",
+     description="Generate SCOPE.md for target-repo at /path/to/SCOPE.md",
-     payload={"repo_slug": "target-repo", "output_path": "/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.