From d5767b282a8d725f776116d0f67f775c332f2f49 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 30 Apr 2026 16:21:57 +0200 Subject: [PATCH] New workplans --- ...REG-WP-0005-scope-md-generation-feature.md | 202 ++++++++++++++++++ ...06-rename-to-repo-scoping-and-integrate.md | 196 +++++++++++++++++ 2 files changed, 398 insertions(+) create mode 100644 workplans/RREG-WP-0005-scope-md-generation-feature.md create mode 100644 workplans/RREG-WP-0006-rename-to-repo-scoping-and-integrate.md diff --git a/workplans/RREG-WP-0005-scope-md-generation-feature.md b/workplans/RREG-WP-0005-scope-md-generation-feature.md new file mode 100644 index 0000000..e6804ee --- /dev/null +++ b/workplans/RREG-WP-0005-scope-md-generation-feature.md @@ -0,0 +1,202 @@ +--- +id: RREG-WP-0005 +type: workplan +title: "SCOPE.md Generation Feature" +domain: capabilities +repo: repo-registry +status: todo +owner: codex +topic_slug: foerster-capabilities +created: "2026-04-30" +updated: "2026-04-30" +state_hub_workstream_id: "5da7ddd9-b192-4271-ba86-c5365405a685" +--- + +# RREG-WP-0005 — SCOPE.md Generation Feature + +## Goal + +Implement SCOPE.md generation and structured update as a first-class output +capability of repo-registry. SCOPE.md is the human- and agent-facing entry +point to a repository's utility story. Its sections map directly onto the +characteristics hierarchy (Scope → Ability → Capability → Feature → Observed +Facts with Evidence), so repo-registry — which already holds this data for +analysed repos — is the natural producer. + +This workplan: (1) establishes the SCOPE.md reference spec inside repo-registry +as the definitive document; (2) builds a generator that maps approved +characteristics to SCOPE.md sections; (3) builds a validator/differ so stale +files can be detected; (4) exposes the feature via API endpoints and (5) +registers the `scope.generate` and `scope.update` capabilities in the custodian +so routing can find them. + +Depends on: RREG-WP-0004 (classification model must be in place) +Unblocks: RREG-WP-0006 + +## T01: Own the SCOPE.md reference specification + +```task +id: RREG-WP-0005-T01 +status: todo +priority: high +state_hub_task_id: "83154aae-dd06-4329-8df6-3906b2bf0f14" +``` + +Port `state-hub/dashboard/src/docs/scope.md` from the-custodian into +`repo-registry/docs/scope-md-spec.md` and upgrade it to reflect the full +characteristics hierarchy. + +Key changes to the spec: +- Map each of the 11 sections to its source in the characteristics model: + - **One-liner / Core Idea** ← Scope characteristic text + - **In Scope / Out of Scope** ← Ability-level characteristics (what the + repo enables vs. what is explicitly absent) + - **Relevant When / Not Relevant When** ← Feature-level characteristics + with primary_class `business-usecase` + - **Current State** ← Observed Facts aggregated by scanner + - **How It Fits** ← Support/evidence references between characteristics and + other repos + - **Terminology** ← Domain term facts extracted by scanner or LLM + - **Related / Overlapping** ← Cross-repo support references + - **Provided Capabilities** ← Capability characteristics (machine-readable + blocks, format unchanged from existing spec) +- Document what sections are auto-generated vs. curator-owned (require human + review before writing) +- Cross-reference `docs/characteristic-evidence-model.md` and + `docs/classification-strategy.md` + +Coordinate with the-custodian: once this spec is stable, the copy at +`state-hub/dashboard/src/docs/scope.md` should redirect here as the source +of truth (or be removed in RREG-WP-0006). + +Acceptance: `docs/scope-md-spec.md` exists, covers all 11 sections with +explicit characteristic-to-section mappings, and is consistent with the +existing template at `state-hub/scripts/project_rules/scope.template`. + +## T02: Build SCOPE.md generator + +```task +id: RREG-WP-0005-T02 +status: todo +priority: high +state_hub_task_id: "39feb7ea-72ca-4d99-8094-b006df605dbe" +``` + +New module `src/repo_registry/scope/generator.py`. + +Given a repo slug with approved characteristics, produce a SCOPE.md string: + +1. **Retrieve** approved characteristics from DB: scope (root), abilities, + capabilities, features, facts, support references +2. **Map** each section following the spec from T01: + - Pull scope characteristic title/description → one-liner and core idea + - Pull abilities with primary_class grouping → in/out-of-scope bullets + - Pull features with `business-usecase` primary_class → relevant-when bullets + - Pull scanner-produced facts (language, framework, route count, etc.) → + current state indicators + - Pull inter-repo support references → how-it-fits and related sections + - Pull capability characteristics → `## Provided Capabilities` blocks + (emit in the existing `capability` block YAML format) +3. **Render** to Markdown with the exact 11-section structure + +Sections for which no characteristics data exists should render as stubs +with a `` comment so they are obvious in review. + +Expose as `ScopeGenerator.generate(repo_slug: str) -> str`. + +Acceptance: calling `ScopeGenerator.generate("repo-registry")` produces a +valid SCOPE.md; all 11 sections are present; the `## Provided Capabilities` +section contains parseable capability blocks; the output passes the C5b/C5c +checks defined in CUST-WP-0034-T01. + +## T03: Build SCOPE.md validator and differ + +```task +id: RREG-WP-0005-T03 +status: todo +priority: high +state_hub_task_id: "0c9c1347-368a-4657-a039-ae143a6500bd" +``` + +New module `src/repo_registry/scope/validator.py`. + +`ScopeValidator.diff(repo_slug: str, existing_path: Path) -> ScopeDiff`: +- Parse existing SCOPE.md sections +- Generate fresh content via `ScopeGenerator` +- Produce a structured diff: `{section: str, status: "ok"|"stale"|"missing", + current_text: str|None, proposed_text: str|None}` +- A section is `stale` if the current text differs materially from generated + content (use normalized whitespace and stripped Markdown for comparison) +- A section is `missing` if the heading does not appear at all + +`ScopeValidator.validate(path: Path) -> ValidationResult`: +- Check C5a/C5b/C5c rules (mirrors doi_engine logic; no DB needed) +- Return list of issues: `{check: str, severity: "error"|"warn", message: str}` + +Acceptance: `ScopeValidator.diff("repo-registry", Path("SCOPE.md"))` returns +a diff with at least some `ok` sections and surfaces any real gaps; the +validator catches a missing `## Provided Capabilities` section as a `warn`. + +## T04: API endpoints + +```task +id: RREG-WP-0005-T04 +status: todo +priority: high +state_hub_task_id: "a2d1937b-f9e2-480e-8e28-1c12837e1b23" +``` + +Add three endpoints under `/repos/{slug}/scope/`: + +- `GET /repos/{slug}/scope` — generate SCOPE.md from current approved + characteristics and return as `text/plain` (dry-run, does not write to disk) +- `POST /repos/{slug}/scope/write` — generate and write to the repo's local + path (uses `host_paths` from managed_repos, same pattern as + `consistency_check.py`); returns `{written: true, path: str}` +- `GET /repos/{slug}/scope/diff` — return JSON `ScopeDiff` comparing current + file on disk to generated content; returns `{sections: [...], needs_update: bool}` + +All endpoints 404 if the repo slug is not registered or has no approved +characteristics. `/scope/write` 409 if the repo has no known local path on +the current host. + +Acceptance: `GET /repos/repo-registry/scope` returns valid Markdown; `GET +/repos/repo-registry/scope/diff` returns a diff JSON; a `POST` write succeeds +and the written file passes the validator. + +## T05: Register capabilities in custodian + +```task +id: RREG-WP-0005-T05 +status: todo +priority: medium +state_hub_task_id: "e1bd4a4f-3d9a-4384-a254-ef75bd9905b9" +``` + +Add two capability blocks to `SCOPE.md` under `## Provided Capabilities`: + +```capability +type: api +title: scope.generate +description: > + Generates a SCOPE.md from scratch for a registered repo using its approved + characteristics profile (abilities, capabilities, features, facts). +keywords: [scope, scope-md, generation, repository-utility] +``` + +```capability +type: api +title: scope.update +description: > + Diffs an existing SCOPE.md against the current characteristics profile + and returns or writes an updated version. +keywords: [scope, scope-md, update, diff, staleness] +``` + +Then run `make ingest-capabilities REPO=repo-registry` (from the-custodian) +so the custodian's capability catalog picks them up. The routes registered in +CUST-WP-0034-T03 will then resolve correctly. + +Acceptance: `list_capabilities()` in the state-hub MCP returns `scope.generate` +and `scope.update` with `provider_repo: repo-registry`; `request_capability` +with either key resolves without routing error. diff --git a/workplans/RREG-WP-0006-rename-to-repo-scoping-and-integrate.md b/workplans/RREG-WP-0006-rename-to-repo-scoping-and-integrate.md new file mode 100644 index 0000000..41b4e69 --- /dev/null +++ b/workplans/RREG-WP-0006-rename-to-repo-scoping-and-integrate.md @@ -0,0 +1,196 @@ +--- +id: RREG-WP-0006 +type: workplan +title: "Rename to repo-scoping and Full Custodian Integration" +domain: capabilities +repo: repo-registry +status: todo +owner: codex +topic_slug: foerster-capabilities +created: "2026-04-30" +updated: "2026-04-30" +depends_on: + - CUST-WP-0034 + - RREG-WP-0005 +state_hub_workstream_id: "9daccfee-bcfc-49c5-bf68-36ea8c205a09" +--- + +# RREG-WP-0006 — Rename to repo-scoping + Full Custodian Integration + +## Goal + +Complete the identity shift from "repository ability registry" to "repository +scoping service". The name `repo-registry` describes internal mechanics +(registering repos); `repo-scoping` describes the utility value (establishing +and maintaining repository scope). This rename follows naturally from the +SCOPE.md generation feature (RREG-WP-0005) becoming the primary output. + +After the rename: run the first full ecosystem SCOPE.md refresh using the +new capability, validate all attached repos pass the updated DOI C5 checks, +and clean up all references to the old name across the custodian ecosystem. + +Depends on: CUST-WP-0034 (delegation infrastructure), RREG-WP-0005 +(SCOPE.md generation feature must exist before the rename makes sense) + +## T01: Rename the Gitea repository + +```task +id: RREG-WP-0006-T01 +status: todo +priority: high +state_hub_task_id: "55341e24-f936-4c74-86e4-fa084ab4a25c" +``` + +In Gitea: Settings → Rename repository from `repo-registry` to `repo-scoping`. +Gitea will set up a redirect from the old name automatically. + +Then update the local checkout: +```bash +git -C /home/worsch/repo-registry remote set-url origin gitea-remote:coulomb/repo-scoping.git +``` + +Verify the push path works: +```bash +git -C /home/worsch/repo-registry push --dry-run +``` + +Acceptance: `git -C /home/worsch/repo-registry remote -v` shows the new URL; +a dry-run push succeeds. + +## T02: Update state-hub registration and repo path + +```task +id: RREG-WP-0006-T02 +status: todo +priority: high +state_hub_task_id: "8a803b12-d991-48c7-8640-8876320815b1" +``` + +Update the managed_repo record in the state-hub: + +1. Call `update_repo_path()` or PATCH `/repos/repo-registry/` to set the new + slug `repo-scoping` and update `git_url` to the new Gitea URL. +2. Run `make fix-consistency-here REPO_PATH=/home/worsch/repo-registry` so + the consistency checker re-registers the host path under the new slug. +3. Rename the local directory (optional — the directory name is not canonical, + only the git remote URL matters): + ```bash + mv /home/worsch/repo-registry /home/worsch/repo-scoping + ``` + If the directory is renamed, also update any absolute paths that reference + `/home/worsch/repo-registry` in CLAUDE.md files, settings, and scripts. + +Acceptance: `GET /repos/repo-scoping/` returns the managed repo record; +`GET /repos/repo-registry/` returns 404; `make fix-consistency` reports no +slug-mismatch issues. + +## T03: Update all references in the-custodian + +```task +id: RREG-WP-0006-T03 +status: todo +priority: high +state_hub_task_id: "4b630593-cfd7-4313-b774-5f7eeed819ec" +``` + +Search the-custodian for every occurrence of `repo-registry` that refers to +this repository (not the generic concept) and update to `repo-scoping`: + +- `canon/` — project charter files, full_circle_map, concept seeds +- `workplans/` — any workplan that names `repo-registry` as a dependency or + provider repo in capability registrations +- `state-hub/dashboard/src/docs/scope.md` — update cross-references or + replace with a redirect note pointing to `repo-scoping/docs/scope-md-spec.md` +- `agents/agent-scope-analyst.md` — provider repo reference updated in + CUST-WP-0034-T04; verify it reflects the new name here +- `~/.claude/projects/…/memory/MEMORY.md` and memory files — update entries + that name `repo-registry` as the capabilities domain repo +- `CLAUDE.md` (global and project) — if `repo-registry` appears as an example + or reference + +Update the capability registrations (registered in CUST-WP-0034-T03): +PATCH `/capabilities/scope.generate` and `/capabilities/scope.update` to set +`provider_repo: repo-scoping`. + +Acceptance: `grep -r "repo-registry" /home/worsch/the-custodian/` returns no +hits that refer to this repository (hits inside this workplan file are +acceptable as historical references). + +## T04: Run first full ecosystem SCOPE.md refresh + +```task +id: RREG-WP-0006-T04 +status: todo +priority: high +state_hub_task_id: "3f25317f-5d4e-464c-8c76-80f61d6724d3" +``` + +For every registered repo that has a local path available on this host: + +1. `GET /repos/{slug}/scope/diff` — inspect whether SCOPE.md is absent, + stub-only, or genuinely stale +2. For repos where `needs_update: true` or SCOPE.md is absent: issue + `POST /repos/{slug}/scope/write` to generate and write the file +3. For repos where the SCOPE.md is curator-owned text that should not be + overwritten wholesale: review the diff and apply only the sections flagged + as `stale` or `missing`, leaving curator-owned sections untouched + +Priority order for the refresh: +1. Repos with no SCOPE.md at all (C5a fail) +2. Repos with a stub SCOPE.md and no approved characteristics (flag for + analysis in repo-scoping first) +3. Repos with approved characteristics but stale SCOPE.md (C5b/C5c warn) + +Log each write as a progress event on the custodian workstream. + +Acceptance: `make check-doi` across all reachable repos reports no C5a +failures; C5b/C5c warns are reduced to repos genuinely awaiting curator input. + +## T05: Validate full DoI C5 pass and run consistency sync + +```task +id: RREG-WP-0006-T05 +status: todo +priority: medium +state_hub_task_id: "860bbc02-c7f4-46cd-9898-41d3454c3ea5" +``` + +After T04: + +1. Run `make ingest-capabilities-all` to refresh the capability catalog from + all updated SCOPE.md files. +2. Run `make fix-consistency REPO=repo-scoping` to sync workplan task statuses + to the DB. +3. Run `make check-doi` for the custodian and repo-scoping and confirm both + pass C5a/b/c. +4. Verify the dashboard "Repo DoI" page reflects the updated scores. + +Acceptance: no C5a failures ecosystem-wide; the DoI summary endpoint at +`GET /repos/doi/summary` shows improved aggregate C5 scores compared to +pre-workplan baseline. + +## T06: Update SCOPE.md for repo-scoping itself + +```task +id: RREG-WP-0006-T06 +status: todo +priority: medium +state_hub_task_id: "1f5ecca9-1c73-4f30-b0e7-4a065146deeb" +``` + +After the rename, regenerate `SCOPE.md` for repo-scoping to reflect: +- New name in the one-liner and core idea +- Updated "In Scope" to lead with SCOPE.md generation as the primary output +- Updated "Provided Capabilities" blocks (scope.generate, scope.update added + in RREG-WP-0005-T05 now appear) +- "Related / Overlapping" referencing the-custodian as the coordination layer + +Run the generator against itself: +```bash +POST /repos/repo-scoping/scope/write +``` + +Then review and apply any curator-owned sections manually. + +Acceptance: `SCOPE.md` at repo root passes all three C5a/b/c checks; the +one-liner accurately describes the repo-scoping utility.