New workplans

2026-04-30 16:21:57 +02:00
parent 6843840dd8
commit d5767b282a
2 changed files with 398 additions and 0 deletions
--- a/workplans/RREG-WP-0005-scope-md-generation-feature.md
+++ 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 `<!-- needs curator input -->` 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.
--- a/workplans/RREG-WP-0006-rename-to-repo-scoping-and-integrate.md
+++ 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.