From 1697477f5516137cd5eb5fb1a845e64b58d56f59 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 1 May 2026 14:57:24 +0200 Subject: [PATCH] Delegation of scope functionality to repo-scoping completed --- agents/agent-scope-analyst.md | 41 ++++++++- .../CUST-WP-0034-scope-md-delegation-prep.md | 84 +++++++++++++++---- 2 files changed, 110 insertions(+), 15 deletions(-) diff --git a/agents/agent-scope-analyst.md b/agents/agent-scope-analyst.md index 6e6c31b..9cc457a 100644 --- a/agents/agent-scope-analyst.md +++ b/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="", + 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 diff --git a/workplans/CUST-WP-0034-scope-md-delegation-prep.md b/workplans/CUST-WP-0034-scope-md-delegation-prep.md index 1f7d436..34d685b 100644 --- a/workplans/CUST-WP-0034-scope-md-delegation-prep.md +++ b/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 -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. +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. @@ -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", - requesting_repo="the-custodian", - payload={"repo_slug": "target-repo", "output_path": "/path/to/SCOPE.md"} + 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="", + 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.