Feature Availability Evaluation
+ +Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context.
+registry/capabilities/capability.feature-control.evaluate.md
+Updated 2026-06-15 · 6 entries
+Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context.
+registry/capabilities/capability.feature-control.evaluate.md
+Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability.
+registry/capabilities/capability.feature-control.rollout.md
+Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model.
+registry/capabilities/capability.identity.subject-resolution.md
+Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
+registry/capabilities/capability.identity.vocabulary-canonicalize.md
+Register a new capability so it becomes visible for planning and implementation reuse.
+registry/capabilities/capability.registry.register.md
+Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service.
+registry/capabilities/capability.statehub.workstream-coordinate.md
+{summary}
+{path}
+Updated {html.escape(str(index.get('updated', 'unknown')))} · {len(indexed_entries)} entries
+ {body} + + +""" + + +def write_catalog( + index: dict[str, Any], + indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]], +) -> tuple[Path, Path]: + CATALOG_HTML_DIR.mkdir(parents=True, exist_ok=True) + CATALOG_MD.write_text(render_markdown(index, indexed_entries), encoding="utf-8") + CATALOG_HTML.write_text(render_html(index, indexed_entries), encoding="utf-8") + return CATALOG_MD, CATALOG_HTML \ No newline at end of file diff --git a/reuse_surface/cli.py b/reuse_surface/cli.py index 694b5d4..4096d07 100644 --- a/reuse_surface/cli.py +++ b/reuse_surface/cli.py @@ -9,9 +9,9 @@ from typing import Any import yaml from jsonschema import Draft202012Validator +from reuse_surface.catalog import write_catalog +from reuse_surface.overlaps import find_overlaps from reuse_surface.registry import ( - CAPABILITIES_DIR, - INDEX_PATH, ROOT, capability_paths, level_at_least, @@ -115,6 +115,40 @@ def cmd_query(args: argparse.Namespace) -> int: return 0 +def _load_indexed_entries() -> list[tuple[dict[str, Any], dict[str, Any]]]: + index = load_index() + indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]] = [] + for item in index.get("capabilities", []): + path = ROOT / item["path"] + indexed_entries.append((item, parse_front_matter(path))) + return indexed_entries + + +def cmd_overlaps(args: argparse.Namespace) -> int: + indexed_entries = _load_indexed_entries() + candidates = find_overlaps(indexed_entries, threshold=args.threshold) + if not candidates: + print("no overlap candidates") + return 0 + for candidate in candidates: + reasons = "; ".join(candidate.reasons) + print( + f"{candidate.left_id} <> {candidate.right_id} " + f"score={candidate.score:.2f} {reasons}" + ) + print(f"\n{len(candidates)} candidate{'s' if len(candidates) != 1 else ''}") + return 0 + + +def cmd_catalog(args: argparse.Namespace) -> int: + index = load_index() + indexed_entries = _load_indexed_entries() + md_path, html_path = write_catalog(index, indexed_entries) + print(f"ok: wrote {md_path.relative_to(ROOT)}") + print(f"ok: wrote {html_path.relative_to(ROOT)}") + return 0 + + def cmd_export(args: argparse.Namespace) -> int: index = load_index() bundle: dict[str, Any] = { @@ -184,6 +218,22 @@ def main(argv: list[str] | None = None) -> int: ) export.set_defaults(func=cmd_export) + overlaps = subparsers.add_parser( + "overlaps", help="detect potential duplicate capabilities" + ) + overlaps.add_argument( + "--threshold", + type=float, + default=0.28, + help="token similarity threshold (0-1)", + ) + overlaps.set_defaults(func=cmd_overlaps) + + catalog = subparsers.add_parser( + "catalog", help="generate human-readable capability catalog" + ) + catalog.set_defaults(func=cmd_catalog) + args = parser.parse_args(argv) return args.func(args) diff --git a/reuse_surface/overlaps.py b/reuse_surface/overlaps.py new file mode 100644 index 0000000..97ad9fd --- /dev/null +++ b/reuse_surface/overlaps.py @@ -0,0 +1,87 @@ +from __future__ import annotations + +import re +from dataclasses import dataclass +from typing import Any + +TOKEN_RE = re.compile(r"[a-z][a-z0-9-]{2,}") + + +@dataclass +class OverlapCandidate: + left_id: str + right_id: str + score: float + reasons: list[str] + + +def _tokens(text: str) -> set[str]: + return set(TOKEN_RE.findall(text.lower())) + + +def _entry_blob(entry: dict[str, Any], index_item: dict[str, Any]) -> str: + discovery = entry.get("discovery") or {} + parts = [ + index_item.get("name", ""), + index_item.get("summary", ""), + entry.get("id", ""), + " ".join(index_item.get("tags", [])), + discovery.get("intent", ""), + " ".join(discovery.get("includes", [])), + ] + return " ".join(str(part) for part in parts if part) + + +def _relation_overlap(left: dict[str, Any], right: dict[str, Any]) -> list[str]: + reasons: list[str] = [] + left_id = left["id"] + right_id = right["id"] + relations = left.get("relations") or {} + for relation_type, targets in relations.items(): + if not isinstance(targets, list): + continue + if right_id in targets: + reasons.append(f"relation:{relation_type}") + if left_id.split(".")[1] == right_id.split(".")[1]: + reasons.append("shared domain segment") + return reasons + + +def find_overlaps( + indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]], + *, + threshold: float = 0.28, +) -> list[OverlapCandidate]: + candidates: list[OverlapCandidate] = [] + blobs = [ + (_entry_blob(entry, index_item), index_item["id"], entry) + for index_item, entry in indexed_entries + ] + + for i, (left_blob, left_id, left_entry) in enumerate(blobs): + left_tokens = _tokens(left_blob) + for j in range(i + 1, len(blobs)): + right_blob, right_id, right_entry = blobs[j] + right_tokens = _tokens(right_blob) + if not left_tokens or not right_tokens: + continue + score = len(left_tokens & right_tokens) / len(left_tokens | right_tokens) + reasons: list[str] = [] + if score >= threshold: + reasons.append(f"token similarity {score:.2f}") + shared_tags = set(left_entry.get("tags", [])) & set( + right_entry.get("tags", []) + ) + if shared_tags: + reasons.append(f"shared tags: {', '.join(sorted(shared_tags))}") + reasons.extend(_relation_overlap(left_entry, right_entry)) + if reasons and (score >= threshold or len(reasons) > 1): + candidates.append( + OverlapCandidate( + left_id=left_id, + right_id=right_id, + score=score, + reasons=reasons, + ) + ) + return sorted(candidates, key=lambda item: item.score, reverse=True) \ No newline at end of file diff --git a/tools/README.md b/tools/README.md index a8e2b7f..3b35e3f 100644 --- a/tools/README.md +++ b/tools/README.md @@ -42,6 +42,25 @@ reuse-surface export reuse-surface export --format json ``` +### overlaps + +Detect potential duplicate or overlapping capabilities (UC-RS-015). + +```bash +reuse-surface overlaps +reuse-surface overlaps --threshold 0.35 +``` + +### catalog + +Generate human-readable catalog artifacts (UC-RS-018). + +```bash +reuse-surface catalog +``` + +Writes `docs/CapabilityCatalog.md` and `docs/catalog/index.html`. + ## Export format The export bundle includes: @@ -59,6 +78,8 @@ Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019). | Discover capabilities | `reuse-surface query` or read the index | | Validate entry shape | `reuse-surface validate` | | Export for agents | `reuse-surface export --format json` | +| Detect overlap | `reuse-surface overlaps` | +| Publish catalog | `reuse-surface catalog` | ## Related use cases diff --git a/workplans/REUSE-WP-0004-registry-hardening.md b/workplans/REUSE-WP-0004-registry-hardening.md new file mode 100644 index 0000000..da60f56 --- /dev/null +++ b/workplans/REUSE-WP-0004-registry-hardening.md @@ -0,0 +1,66 @@ +--- +id: REUSE-WP-0004 +type: workplan +title: "Registry hardening: CI, overlap detection, and catalog" +domain: helix_forge +repo: reuse-surface +status: finished +owner: codex +topic_slug: helix-forge +created: "2026-06-15" +updated: "2026-06-15" +--- + +# Registry hardening: CI, overlap detection, and catalog + +Follow-up to `docs/IntentScopeGapAnalysis.md` section 8 next recommended work +(priorities 9–11). Raise registry quality through automated CI validation, overlap +reporting (UC-RS-015), and a generated human-readable catalog (UC-RS-018). + +## Add CI Validation Workflow + +```task +id: REUSE-WP-0004-T01 +status: done +priority: high +``` + +Add `.gitea/workflows/ci.yml` that runs on push and pull requests to `main`. +Install the package and run `reuse-surface validate`. Document the workflow in +`AGENTS.md`. + +## Add Overlap Detection Command + +```task +id: REUSE-WP-0004-T02 +status: done +priority: high +``` + +Add `reuse-surface overlaps` that flags potential duplicate or overlapping +capabilities using summary/tags/includes similarity and relation signals. +Document usage in `registry/README.md` and `tools/README.md`. + +## Add Catalog Generation Command + +```task +id: REUSE-WP-0004-T03 +status: done +priority: medium +``` + +Add `reuse-surface catalog` that generates `docs/CapabilityCatalog.md` and +`docs/catalog/index.html` from the index and entry front matter. Group by domain +and show maturity vectors. + +## Refresh Docs And Gap Analysis + +```task +id: REUSE-WP-0004-T04 +status: done +priority: medium +``` + +Update `SCOPE.md`, `tools/README.md`, and `docs/IntentScopeGapAnalysis.md` to +reflect CI, overlaps, and catalog capabilities. Close gap analysis priorities +9–11. \ No newline at end of file