tegwick
f99d77d539
Updated by fix-consistency on 2026-05-01: - update .custodian-brief.md for the-custodian
149 lines
5.0 KiB
Markdown
149 lines
5.0 KiB
Markdown
---
|
|
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.
|