diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index f0211cf..7bbb0e6 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -19,10 +19,18 @@ jobs: python-version: "3.12" - name: Install package - run: python -m pip install -e . + run: python -m pip install -e ".[dev]" - name: Validate capability registry - run: reuse-surface validate --relations + run: reuse-surface validate --relations --fail-on-warnings - name: Compose federated index - run: reuse-surface federation compose \ No newline at end of file + run: reuse-surface federation compose + + - name: Generate catalog and graph + run: | + reuse-surface catalog + reuse-surface graph --check --fail-on-warnings + + - name: Run tests + run: pytest -q \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 8522218..7bbb971 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -130,6 +130,9 @@ artifacts. .venv/bin/reuse-surface federation compose .venv/bin/reuse-surface graph --check +# Automated tests +.venv/bin/pytest -q + # Repository hygiene rg --files git diff --check diff --git a/SCOPE.md b/SCOPE.md index a47d0d4..fce3bb7 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -52,8 +52,11 @@ and agents can: - **Export a machine-readable bundle** with `reuse-surface export` - **Detect overlap candidates** with `reuse-surface overlaps` - **Generate a human-readable catalog** with `reuse-surface catalog` +- **Browse a searchable catalog** at `docs/catalog/search.html` (client-side + filter over `registry.json`) - **Compose federated indexes** with `reuse-surface federation compose` - **Generate relation graphs** with `reuse-surface graph` +- **Explore relations interactively** at `docs/graph/index.html` - **Avoid duplicates** by querying the index and checking overlaps before adding entries Registry tooling availability is **A3** (CLI). The registry product itself is @@ -62,8 +65,6 @@ the index, and CLI automation. ## What Is Not Possible Yet -- Interactive catalog site with live search beyond static HTML export -- Interactive relation graph UI (Mermaid file only) - Network-based federation or cross-org index sync - Packaged releases beyond local `pip install -e .` and Gitea CI validation @@ -72,16 +73,19 @@ See `tools/README.md` for command reference. ## Current State - Status: active MVP registry with CLI tooling. -- Six helix_forge capabilities are registered in `registry/capabilities/`. +- Twelve helix_forge capabilities are registered in `registry/capabilities/`. - `reuse-surface` CLI provides `validate`, `query`, and `export` via `pyproject.toml` and `reuse_surface/`. - `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md` document onboarding and intent-scope tracking. - CI validates the registry and composes federation on push/PR. - Federated index: `registry/indexes/federated.yaml`. -- Relation graph: `docs/graph/capability-graph.mmd`. -- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0005`. -- **Self-assessed vector:** `D5 / A3 / C4 / R2` (see gap analysis). +- Relation graph: `docs/graph/capability-graph.mmd` and explorer at + `docs/graph/index.html`. +- Searchable catalog: `docs/catalog/search.html`. +- Test suite: `tests/` (pytest). +- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0009`. +- **Self-assessed vector:** `D5 / A3 / C4 / R3` (see gap analysis). ## Repository Layout @@ -112,8 +116,10 @@ reuse-surface/ - Registry index: registry/indexes/capabilities.yaml - Registry guidance: registry/README.md - Generated catalog: docs/CapabilityCatalog.md +- Searchable catalog: docs/catalog/search.html - Federation guide: docs/RegistryFederation.md - Relation graph: docs/graph/capability-graph.mmd +- Graph explorer: docs/graph/index.html - CLI reference: tools/README.md - Agent instructions: AGENTS.md - Workplans: workplans/ \ No newline at end of file diff --git a/docs/CapabilityCatalog.md b/docs/CapabilityCatalog.md index 7186681..af73e7d 100644 --- a/docs/CapabilityCatalog.md +++ b/docs/CapabilityCatalog.md @@ -2,12 +2,45 @@ **Domain:** helix_forge **Updated:** 2026-06-15 -**Entries:** 6 +**Entries:** 12 Generated by `reuse-surface catalog`. Do not edit manually. ## helix_forge +### Organizational Event Coordination + +- **ID:** `capability.activity.event-coordinate` +- **Vector:** D3 / A1 / C1 / R0 +- **Owner:** activity-core +- **Path:** `registry/capabilities/capability.activity.event-coordinate.md` +- **Summary:** Coordinate structured responses to cross-domain events through activity workflows and automation. + +**Known limitations:** +- early discovery stage + +### Audit Event Retention + +- **ID:** `capability.audit.event-retain` +- **Vector:** D4 / A2 / C2 / R1 +- **Owner:** audit-core +- **Path:** `registry/capabilities/capability.audit.event-retain.md` +- **Summary:** Collect, normalize, retain, and search audit events with integrity evidence across tenants. + +**Known limitations:** +- consumer evidence not yet collected in registry + +### Authorization Policy Evaluation + +- **ID:** `capability.authorization.policy-evaluate` +- **Vector:** D4 / A2 / C2 / R1 +- **Owner:** flex-auth +- **Path:** `registry/capabilities/capability.authorization.policy-evaluate.md` +- **Summary:** Evaluate access decisions from policy-as-code rules for subjects, resources, and actions. + +**Known limitations:** +- maturity evidence is registry-external today + ### Feature Availability Evaluation - **ID:** `capability.feature-control.evaluate` @@ -26,18 +59,29 @@ Generated by `reuse-surface catalog`. Do not edit manually. - **Vector:** D4 / A2 / C2 / R1 - **Owner:** feature-control - **Path:** `registry/capabilities/capability.feature-control.rollout.md` -- **Summary:** Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability. +- **Summary:** Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules. **Known limitations:** - distinguish carefully from capability.feature-control.evaluate +### Feature Visibility Control + +- **ID:** `capability.feature-control.visibility` +- **Vector:** D4 / A2 / C2 / R1 +- **Owner:** feature-control +- **Path:** `registry/capabilities/capability.feature-control.visibility.md` +- **Summary:** Control whether features are visible or hidden for subjects without changing entitlement or authorization. + +**Known limitations:** +- implementation may be bundled with evaluate SDK today + ### Identity Subject Resolution - **ID:** `capability.identity.subject-resolution` - **Vector:** D3 / A0 / C1 / R0 - **Owner:** identity-canon - **Path:** `registry/capabilities/capability.identity.subject-resolution.md` -- **Summary:** Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model. +- **Summary:** Resolve who or what is acting by mapping principals, accounts, actors, and identifiers to a stable subject model. **Known limitations:** - resolver artifacts are not yet available @@ -48,7 +92,7 @@ Generated by `reuse-surface catalog`. Do not edit manually. - **Vector:** D4 / A0 / C2 / R0 - **Owner:** identity-canon - **Path:** `registry/capabilities/capability.identity.vocabulary-canonicalize.md` -- **Summary:** Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains. +- **Summary:** Define an implementation-neutral vocabulary for identity-related concepts across overlapping domains. **Known limitations:** - source-note backfill is incomplete @@ -66,13 +110,35 @@ Generated by `reuse-surface catalog`. Do not edit manually. - manual index updates are required after adding an entry - duplicate detection is guidance-only in the MVP +### Registry Entry Validation + +- **ID:** `capability.registry.validate` +- **Vector:** D4 / A3 / C3 / R2 +- **Owner:** reuse-surface +- **Path:** `registry/capabilities/capability.registry.validate.md` +- **Summary:** Validate capability registry entries against schema, index consistency, and relation integrity. + +**Known limitations:** +- warnings do not fail CI unless --fail-on-warnings is set + +### Work Progress Logging + +- **ID:** `capability.statehub.progress-log` +- **Vector:** D4 / A4 / C3 / R2 +- **Owner:** state-hub +- **Path:** `registry/capabilities/capability.statehub.progress-log.md` +- **Summary:** Record progress events, decisions, and session notes against workstreams and tasks in State Hub. + +**Known limitations:** +- hub must be running locally or via tunnel + ### Workstream And Task Coordination - **ID:** `capability.statehub.workstream-coordinate` - **Vector:** D4 / A4 / C3 / R2 - **Owner:** state-hub - **Path:** `registry/capabilities/capability.statehub.workstream-coordinate.md` -- **Summary:** Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service. +- **Summary:** Track active workstreams, tasks, progress, and consistency across domain repositories. **Known limitations:** - requires running State Hub locally or via tunnel diff --git a/docs/CapabilityRegistryConcept.md b/docs/CapabilityRegistryConcept.md index bfb43a2..5602f79 100644 --- a/docs/CapabilityRegistryConcept.md +++ b/docs/CapabilityRegistryConcept.md @@ -85,10 +85,13 @@ tools/ → CLI validate, query, export **Consumption flow** -1. Read `registry/indexes/capabilities.yaml`. -2. Filter by vector, tags, or consumption mode. +1. Read `registry/indexes/capabilities.yaml` or open `docs/catalog/search.html` + for client-side filter by name, tags, vector, and consumption mode. +2. Filter by vector, tags, or consumption mode (`reuse-surface query`). 3. Open candidate entry files for scope, relations, and guidance. 4. Prefer planning reuse at D3+ and implementation reuse at A2+. +5. Browse relation structure in `docs/graph/index.html` after running + `reuse-surface graph`. --- diff --git a/docs/IntentScopeGapAnalysis.md b/docs/IntentScopeGapAnalysis.md index 3222a11..019731b 100644 --- a/docs/IntentScopeGapAnalysis.md +++ b/docs/IntentScopeGapAnalysis.md @@ -18,16 +18,15 @@ with **A3 CLI tooling** (`validate`, `query`, `export`) atop Markdown-first authoring. The two documents are **directionally aligned** on registry-first reuse, four -maturity dimensions, and human/agent consumers. REUSE-WP-0003 closed the -priority gaps from section 8. Remaining gaps are primarily scale, automation, -and presentation concerns: +maturity dimensions, and human/agent consumers. REUSE-WP-0003 through +REUSE-WP-0009 closed the priority gaps from section 8 except network +federation. Remaining gaps are primarily scale and cross-org sync: -1. **Planning analytics** — no gap reports, overlap detection, or catalog site. -2. **Reliability depth** — registry product dogfood evidence is early (R2). -3. **Document cross-coverage** — SCOPE still carries operational detail INTENT +1. **Network federation** — local compose only; no remote index fetch. +2. **Document cross-coverage** — SCOPE still carries operational detail INTENT omits; INTENT success criteria are not fully enumerated in SCOPE. -**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R2` +**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R3` --- @@ -238,15 +237,16 @@ docs remain incomplete. | Signal | State | |---|---| -| Automated tests | None | -| Schema validation in CI | None | +| Automated tests | `tests/` — pytest covers validate, query, export, overlaps, federation, graph, catalog | +| Schema validation in CI | `.gitea/workflows/ci.yml` — validate, federation, catalog, graph, pytest | | Consumer feedback on registry workflows | None | | Production or repeated agent usage evidence | None | | Known friction | Manual index maintenance; schema/INTENT field naming drift | -**Overall reliability vs INTENT consumer-evidence framing:** **R0 (Unknown)** for -the registry product itself. Individual registered capabilities may carry their -own evidence (e.g. feature-control at R3). +**Overall reliability vs INTENT consumer-evidence framing:** **R3 (Proven in +Development)** for registry CLI tooling — pytest suite and CI gates exercise +core commands. Individual registered capabilities may carry their own evidence +(e.g. feature-control at R3). --- @@ -273,11 +273,11 @@ own evidence (e.g. feature-control at R3). | 12 | Registry federation | `federation compose` + federated index | Closed (WP-0005) | | 14 | Graph visualization | `reuse-surface graph` Mermaid output | Closed (WP-0005) | -| Priority | Gap | Suggested outcome | -|---|---|---| -| 13 | Interactive catalog | Searchable catalog UI beyond static HTML | -| 15 | Network federation | Remote index fetch and cross-org sync | -| 16 | Graph UI | Interactive relation graph explorer | +| Priority | Gap | Outcome | Status | +|---|---|---|---| +| 13 | Interactive catalog | `docs/catalog/search.html` + `registry.json` | Closed (WP-0007) | +| 15 | Network federation | Remote index fetch and cross-org sync | Open (WP-0010) | +| 16 | Graph UI | `docs/graph/index.html` explorer | Closed (WP-0008) | --- @@ -298,4 +298,8 @@ own evidence (e.g. feature-control at R3). | 2026-06-15 | Initial analysis after REUSE-WP-0002 completion | | 2026-06-15 | REUSE-WP-0003 closed priority gaps 1–8; vector updated to D5/A3/C4/R2 | | 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI) | -| 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs) | \ No newline at end of file +| 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs) | +| 2026-06-15 | REUSE-WP-0006 expanded registry to 12 capabilities; relation hygiene clean | +| 2026-06-15 | REUSE-WP-0007 closed priority 13 (searchable catalog UI) | +| 2026-06-15 | REUSE-WP-0008 closed priority 16 (graph explorer) | +| 2026-06-15 | REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3 | \ No newline at end of file diff --git a/docs/catalog/index.html b/docs/catalog/index.html index 9a5ca52..14f5268 100644 --- a/docs/catalog/index.html +++ b/docs/catalog/index.html @@ -15,8 +15,26 @@

Capability Catalog

-

Updated 2026-06-15 · 6 entries

+

Updated 2026-06-15 · 12 entries

helix_forge

+
+

Organizational Event Coordination

+

capability.activity.event-coordinate · D3 / A1 / C1 / R0

+

Coordinate structured responses to cross-domain events through activity workflows and automation.

+

registry/capabilities/capability.activity.event-coordinate.md

+
+
+

Audit Event Retention

+

capability.audit.event-retain · D4 / A2 / C2 / R1

+

Collect, normalize, retain, and search audit events with integrity evidence across tenants.

+

registry/capabilities/capability.audit.event-retain.md

+
+
+

Authorization Policy Evaluation

+

capability.authorization.policy-evaluate · D4 / A2 / C2 / R1

+

Evaluate access decisions from policy-as-code rules for subjects, resources, and actions.

+

registry/capabilities/capability.authorization.policy-evaluate.md

+

Feature Availability Evaluation

capability.feature-control.evaluate · D5 / A4 / C3 / R3

@@ -26,19 +44,25 @@

Feature Rollout Control

capability.feature-control.rollout · D4 / A2 / C2 / R1

-

Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability.

+

Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules.

registry/capabilities/capability.feature-control.rollout.md

+
+

Feature Visibility Control

+

capability.feature-control.visibility · D4 / A2 / C2 / R1

+

Control whether features are visible or hidden for subjects without changing entitlement or authorization.

+

registry/capabilities/capability.feature-control.visibility.md

+

Identity Subject Resolution

capability.identity.subject-resolution · D3 / A0 / C1 / R0

-

Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model.

+

Resolve who or what is acting by mapping principals, accounts, actors, and identifiers to a stable subject model.

registry/capabilities/capability.identity.subject-resolution.md

Identity Vocabulary Canonicalization

capability.identity.vocabulary-canonicalize · D4 / A0 / C2 / R0

-

Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.

+

Define an implementation-neutral vocabulary for identity-related concepts across overlapping domains.

registry/capabilities/capability.identity.vocabulary-canonicalize.md

@@ -47,10 +71,22 @@

Register a new capability so it becomes visible for planning and implementation reuse.

registry/capabilities/capability.registry.register.md

+
+

Registry Entry Validation

+

capability.registry.validate · D4 / A3 / C3 / R2

+

Validate capability registry entries against schema, index consistency, and relation integrity.

+

registry/capabilities/capability.registry.validate.md

+
+
+

Work Progress Logging

+

capability.statehub.progress-log · D4 / A4 / C3 / R2

+

Record progress events, decisions, and session notes against workstreams and tasks in State Hub.

+

registry/capabilities/capability.statehub.progress-log.md

+

Workstream And Task Coordination

capability.statehub.workstream-coordinate · D4 / A4 / C3 / R2

-

Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service.

+

Track active workstreams, tasks, progress, and consistency across domain repositories.

registry/capabilities/capability.statehub.workstream-coordinate.md

diff --git a/docs/catalog/registry.json b/docs/catalog/registry.json new file mode 100644 index 0000000..ee9e4cd --- /dev/null +++ b/docs/catalog/registry.json @@ -0,0 +1,226 @@ +{ + "domain": "helix_forge", + "updated": "2026-06-15", + "capabilities": [ + { + "id": "capability.activity.event-coordinate", + "name": "Organizational Event Coordination", + "summary": "Coordinate structured responses to cross-domain events through activity workflows and automation.", + "vector": "D3 / A1 / C1 / R0", + "domain": "helix_forge", + "status": "draft", + "owner": "activity-core", + "path": "registry/capabilities/capability.activity.event-coordinate.md", + "tags": [ + "activity", + "coordination", + "automation" + ], + "consumption_modes": [ + "informational" + ] + }, + { + "id": "capability.audit.event-retain", + "name": "Audit Event Retention", + "summary": "Collect, normalize, retain, and search audit events with integrity evidence across tenants.", + "vector": "D4 / A2 / C2 / R1", + "domain": "helix_forge", + "status": "draft", + "owner": "audit-core", + "path": "registry/capabilities/capability.audit.event-retain.md", + "tags": [ + "audit", + "retention", + "compliance" + ], + "consumption_modes": [ + "source module" + ] + }, + { + "id": "capability.authorization.policy-evaluate", + "name": "Authorization Policy Evaluation", + "summary": "Evaluate access decisions from policy-as-code rules for subjects, resources, and actions.", + "vector": "D4 / A2 / C2 / R1", + "domain": "helix_forge", + "status": "draft", + "owner": "flex-auth", + "path": "registry/capabilities/capability.authorization.policy-evaluate.md", + "tags": [ + "authorization", + "policy", + "flex-auth" + ], + "consumption_modes": [ + "source module" + ] + }, + { + "id": "capability.feature-control.evaluate", + "name": "Feature Availability Evaluation", + "summary": "Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context.", + "vector": "D5 / A4 / C3 / R3", + "domain": "helix_forge", + "status": "draft", + "owner": "feature-control", + "path": "registry/capabilities/capability.feature-control.evaluate.md", + "tags": [ + "feature-control", + "evaluation", + "sdk" + ], + "consumption_modes": [ + "SDK", + "service API" + ] + }, + { + "id": "capability.feature-control.rollout", + "name": "Feature Rollout Control", + "summary": "Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules.", + "vector": "D4 / A2 / C2 / R1", + "domain": "helix_forge", + "status": "draft", + "owner": "feature-control", + "path": "registry/capabilities/capability.feature-control.rollout.md", + "tags": [ + "feature-control", + "rollout", + "planning" + ], + "consumption_modes": [ + "source module", + "SDK" + ] + }, + { + "id": "capability.feature-control.visibility", + "name": "Feature Visibility Control", + "summary": "Control whether features are visible or hidden for subjects without changing entitlement or authorization.", + "vector": "D4 / A2 / C2 / R1", + "domain": "helix_forge", + "status": "draft", + "owner": "feature-control", + "path": "registry/capabilities/capability.feature-control.visibility.md", + "tags": [ + "feature-control", + "visibility" + ], + "consumption_modes": [ + "source module" + ] + }, + { + "id": "capability.identity.subject-resolution", + "name": "Identity Subject Resolution", + "summary": "Resolve who or what is acting by mapping principals, accounts, actors, and identifiers to a stable subject model.", + "vector": "D3 / A0 / C1 / R0", + "domain": "helix_forge", + "status": "draft", + "owner": "identity-canon", + "path": "registry/capabilities/capability.identity.subject-resolution.md", + "tags": [ + "identity", + "subject", + "architecture" + ], + "consumption_modes": [ + "informational" + ] + }, + { + "id": "capability.identity.vocabulary-canonicalize", + "name": "Identity Vocabulary Canonicalization", + "summary": "Define an implementation-neutral vocabulary for identity-related concepts across overlapping domains.", + "vector": "D4 / A0 / C2 / R0", + "domain": "helix_forge", + "status": "draft", + "owner": "identity-canon", + "path": "registry/capabilities/capability.identity.vocabulary-canonicalize.md", + "tags": [ + "identity", + "terminology", + "research" + ], + "consumption_modes": [ + "informational" + ] + }, + { + "id": "capability.registry.register", + "name": "Capability Registration", + "summary": "Register a new capability so it becomes visible for planning and implementation reuse.", + "vector": "D3 / A3 / C2 / R2", + "domain": "helix_forge", + "status": "draft", + "owner": "reuse-surface", + "path": "registry/capabilities/capability.registry.register.md", + "tags": [ + "registry", + "governance", + "meta" + ], + "consumption_modes": [ + "informational", + "markdown authoring", + "cli" + ] + }, + { + "id": "capability.registry.validate", + "name": "Registry Entry Validation", + "summary": "Validate capability registry entries against schema, index consistency, and relation integrity.", + "vector": "D4 / A3 / C3 / R2", + "domain": "helix_forge", + "status": "draft", + "owner": "reuse-surface", + "path": "registry/capabilities/capability.registry.validate.md", + "tags": [ + "registry", + "validation", + "cli" + ], + "consumption_modes": [ + "cli" + ] + }, + { + "id": "capability.statehub.progress-log", + "name": "Work Progress Logging", + "summary": "Record progress events, decisions, and session notes against workstreams and tasks in State Hub.", + "vector": "D4 / A4 / C3 / R2", + "domain": "helix_forge", + "status": "draft", + "owner": "state-hub", + "path": "registry/capabilities/capability.statehub.progress-log.md", + "tags": [ + "state-hub", + "progress", + "coordination" + ], + "consumption_modes": [ + "service API" + ] + }, + { + "id": "capability.statehub.workstream-coordinate", + "name": "Workstream And Task Coordination", + "summary": "Track active workstreams, tasks, progress, and consistency across domain repositories.", + "vector": "D4 / A4 / C3 / R2", + "domain": "helix_forge", + "status": "draft", + "owner": "state-hub", + "path": "registry/capabilities/capability.statehub.workstream-coordinate.md", + "tags": [ + "state-hub", + "coordination", + "workplans" + ], + "consumption_modes": [ + "service API", + "HTTP REST" + ] + } + ] +} \ No newline at end of file diff --git a/docs/catalog/search.html b/docs/catalog/search.html new file mode 100644 index 0000000..9147e8b --- /dev/null +++ b/docs/catalog/search.html @@ -0,0 +1,44 @@ + + + + + Capability Catalog Search + + + +

Capability Catalog

+

Client-side search over registry.json. Generated by reuse-surface catalog.

+ +

+
+ + + diff --git a/docs/graph/capability-graph.mmd b/docs/graph/capability-graph.mmd index cbd0716..7ae3738 100644 --- a/docs/graph/capability-graph.mmd +++ b/docs/graph/capability-graph.mmd @@ -1,24 +1,42 @@ graph LR + capability_activity_event_coordinate["capability.activity.event-coordinate
D3 / A1 / C1 / R0"] + capability_audit_event_retain["capability.audit.event-retain
D4 / A2 / C2 / R1"] + capability_authorization_policy_evaluate["capability.authorization.policy-evaluate
D4 / A2 / C2 / R1"] capability_feature_control_evaluate["capability.feature-control.evaluate
D5 / A4 / C3 / R3"] capability_feature_control_rollout["capability.feature-control.rollout
D4 / A2 / C2 / R1"] + capability_feature_control_visibility["capability.feature-control.visibility
D4 / A2 / C2 / R1"] capability_identity_subject_resolution["capability.identity.subject-resolution
D3 / A0 / C1 / R0"] capability_identity_vocabulary_canonicalize["capability.identity.vocabulary-canonicalize
D4 / A0 / C2 / R0"] capability_registry_register["capability.registry.register
D3 / A3 / C2 / R2"] + capability_registry_validate["capability.registry.validate
D4 / A3 / C3 / R2"] + capability_statehub_progress_log["capability.statehub.progress-log
D4 / A4 / C3 / R2"] capability_statehub_workstream_coordinate["capability.statehub.workstream-coordinate
D4 / A4 / C3 / R2"] - capability_registry_register -->|supports| capability_feature_control_evaluate - capability_registry_register -->|supports| capability_identity_vocabulary_canonicalize - capability_registry_register -->|related_to| capability_registry_validate + capability_activity_event_coordinate -->|related_to| capability_statehub_workstream_coordinate + capability_activity_event_coordinate -->|related_to| capability_audit_event_retain + capability_audit_event_retain -->|related_to| capability_activity_event_coordinate + capability_audit_event_retain -->|related_to| capability_statehub_progress_log + capability_authorization_policy_evaluate -->|depends_on| capability_identity_subject_resolution + capability_authorization_policy_evaluate -->|related_to| capability_feature_control_evaluate capability_feature_control_evaluate -->|depends_on| capability_identity_vocabulary_canonicalize capability_feature_control_evaluate -->|supports| capability_registry_register capability_feature_control_evaluate -->|related_to| capability_feature_control_rollout capability_feature_control_evaluate -->|related_to| capability_feature_control_visibility capability_feature_control_rollout -->|depends_on| capability_feature_control_evaluate capability_feature_control_rollout -->|related_to| capability_feature_control_visibility - capability_identity_vocabulary_canonicalize -->|supports| capability_feature_control_evaluate - capability_identity_vocabulary_canonicalize -->|supports| capability_registry_register - capability_identity_vocabulary_canonicalize -->|related_to| capability_identity_subject_resolution + capability_feature_control_visibility -->|depends_on| capability_feature_control_evaluate + capability_feature_control_visibility -->|related_to| capability_feature_control_rollout capability_identity_subject_resolution -->|depends_on| capability_identity_vocabulary_canonicalize capability_identity_subject_resolution -->|supports| capability_feature_control_evaluate capability_identity_subject_resolution -->|supports| capability_statehub_workstream_coordinate + capability_identity_vocabulary_canonicalize -->|supports| capability_feature_control_evaluate + capability_identity_vocabulary_canonicalize -->|supports| capability_registry_register + capability_identity_vocabulary_canonicalize -->|related_to| capability_identity_subject_resolution + capability_registry_register -->|supports| capability_feature_control_evaluate + capability_registry_register -->|supports| capability_identity_vocabulary_canonicalize + capability_registry_register -->|related_to| capability_registry_validate + capability_registry_validate -->|depends_on| capability_registry_register + capability_registry_validate -->|related_to| capability_registry_register + capability_statehub_progress_log -->|depends_on| capability_statehub_workstream_coordinate + capability_statehub_progress_log -->|related_to| capability_statehub_workstream_coordinate capability_statehub_workstream_coordinate -->|supports| capability_registry_register capability_statehub_workstream_coordinate -->|related_to| capability_statehub_progress_log diff --git a/docs/graph/index.html b/docs/graph/index.html new file mode 100644 index 0000000..0eb7ef2 --- /dev/null +++ b/docs/graph/index.html @@ -0,0 +1,23 @@ + + + + + Capability Relation Graph + + + + +

Capability Relation Graph

+

Generated from entry relations fields. Regenerate with reuse-surface graph.

+ 

+  
+
+
diff --git a/pyproject.toml b/pyproject.toml
index 9d5128e..b6622a0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -13,6 +13,11 @@ dependencies = [
   "pyyaml>=6.0",
 ]
 
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
 [project.scripts]
 reuse-surface = "reuse_surface.cli:main"
 
diff --git a/registry/README.md b/registry/README.md
index 2920f29..5eb1e2a 100644
--- a/registry/README.md
+++ b/registry/README.md
@@ -138,7 +138,10 @@ reuse-surface graph
 reuse-surface graph --check
 ```
 
-Output: `docs/graph/capability-graph.mmd`
+Outputs:
+
+- `docs/graph/capability-graph.mmd` — Mermaid source
+- `docs/graph/index.html` — in-browser explorer (also regenerated by `catalog`)
 
 ## Promote a capability
 
diff --git a/registry/capabilities/capability.activity.event-coordinate.md b/registry/capabilities/capability.activity.event-coordinate.md
new file mode 100644
index 0000000..fd0037a
--- /dev/null
+++ b/registry/capabilities/capability.activity.event-coordinate.md
@@ -0,0 +1,77 @@
+---
+id: capability.activity.event-coordinate
+name: Organizational Event Coordination
+summary: Coordinate structured responses to cross-domain events through activity workflows and automation.
+owner: activity-core
+status: draft
+domain: helix_forge
+tags: [activity, coordination, automation]
+
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: medium
+    rationale: activity-core INTENT defines org-wide event response boundary.
+  availability:
+    current: A1
+    target: A4
+    confidence: low
+    rationale: Conceptual workflows exist; consumable API surface still emerging.
+
+external_evidence:
+  completeness:
+    level: C1
+    name: Fragmentary
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - problem and boundary documented in INTENT
+    broken_expectations:
+      - no registry-native automation artifacts indexed yet
+    out_of_scope_expectations:
+      - owning domain-specific business logic
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks: []
+
+discovery:
+  intent: >
+    Give the organization a structural home for responding to events across repos
+    and domains in an auditable, automation-ready way.
+  includes:
+    - event-triggered coordination
+    - cross-domain maintenance workflows
+  excludes:
+    - single-repo cron replacements only
+  use_cases: []
+
+availability:
+  current_level: A1
+  target_level: A4
+  current_artifacts:
+    - activity-core/INTENT.md
+  consumption_modes:
+    - informational
+
+relations:
+  depends_on: []
+  related_to:
+    - capability.statehub.workstream-coordinate
+    - capability.audit.event-retain
+
+consumer_guidance:
+  recommended_for:
+    - planning org-wide event response patterns
+  not_recommended_for:
+    - assuming production automation is available
+  known_limitations:
+    - early discovery stage
+---
+
+# Organizational Event Coordination
+
+activity-core coordinates how the org responds to events—not the domain logic
+inside each repo.
\ No newline at end of file
diff --git a/registry/capabilities/capability.audit.event-retain.md b/registry/capabilities/capability.audit.event-retain.md
new file mode 100644
index 0000000..1ce2b46
--- /dev/null
+++ b/registry/capabilities/capability.audit.event-retain.md
@@ -0,0 +1,80 @@
+---
+id: capability.audit.event-retain
+name: Audit Event Retention
+summary: Collect, normalize, retain, and search audit events with integrity evidence across tenants.
+owner: audit-core
+status: draft
+domain: helix_forge
+tags: [audit, retention, compliance]
+
+maturity:
+  discovery:
+    current: D4
+    target: D6
+    confidence: medium
+    rationale: audit-core INTENT defines full audit fabric scope and integration boundaries.
+  availability:
+    current: A2
+    target: A5
+    confidence: low
+    rationale: Core modules exist; deployable service packaging in progress.
+
+external_evidence:
+  completeness:
+    level: C2
+    name: Partial
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - retention and integrity goals documented
+    broken_expectations:
+      - federation with all platform runtimes not proven in registry
+    out_of_scope_expectations:
+      - application business audit semantics ownership
+  reliability:
+    level: R1
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - multi-tenant isolation not evidenced here
+
+discovery:
+  intent: >
+    Provide independent audit fabric for collecting, retaining, searching, and
+    proving integrity of audit events.
+  includes:
+    - audit ingestion
+    - retention policy
+    - search and export
+    - tamper evidence
+  excludes:
+    - generating domain business events
+  use_cases: []
+
+availability:
+  current_level: A2
+  target_level: A5
+  current_artifacts:
+    - audit-core/
+  consumption_modes:
+    - source module
+
+relations:
+  depends_on: []
+  related_to:
+    - capability.activity.event-coordinate
+    - capability.statehub.progress-log
+
+consumer_guidance:
+  recommended_for:
+    - planning audit retention independent of a single product
+  not_recommended_for:
+    - replacing application-level logging only
+  known_limitations:
+    - consumer evidence not yet collected in registry
+---
+
+# Audit Event Retention
+
+Audit Core provides the retention and integrity layer for audit events across
+the platform.
\ No newline at end of file
diff --git a/registry/capabilities/capability.authorization.policy-evaluate.md b/registry/capabilities/capability.authorization.policy-evaluate.md
new file mode 100644
index 0000000..be22db6
--- /dev/null
+++ b/registry/capabilities/capability.authorization.policy-evaluate.md
@@ -0,0 +1,80 @@
+---
+id: capability.authorization.policy-evaluate
+name: Authorization Policy Evaluation
+summary: Evaluate access decisions from policy-as-code rules for subjects, resources, and actions.
+owner: flex-auth
+status: draft
+domain: helix_forge
+tags: [authorization, policy, flex-auth]
+
+maturity:
+  discovery:
+    current: D4
+    target: D6
+    confidence: medium
+    rationale: flex-auth INTENT defines policy-as-code boundary and enterprise growth path.
+  availability:
+    current: A2
+    target: A5
+    confidence: low
+    rationale: Policy registry and evaluation logic exist in repo; service packaging evolving.
+
+external_evidence:
+  completeness:
+    level: C2
+    name: Partial
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - policy-as-code intent documented
+    broken_expectations:
+      - not yet indexed from flex-auth native registry
+    out_of_scope_expectations:
+      - identity proofing
+  reliability:
+    level: R1
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - early implementation phase
+
+discovery:
+  intent: >
+    Provide inspectable authorization decisions between verified identity and
+    protected resources using policy-as-code.
+  includes:
+    - policy evaluation
+    - authorization registry
+    - decision explainability
+  excludes:
+    - identity issuance
+    - authentication protocols
+  use_cases: []
+
+availability:
+  current_level: A2
+  target_level: A5
+  current_artifacts:
+    - flex-auth/
+  consumption_modes:
+    - source module
+
+relations:
+  depends_on:
+    - capability.identity.subject-resolution
+  related_to:
+    - capability.feature-control.evaluate
+
+consumer_guidance:
+  recommended_for:
+    - planning authorization layer between identity and resources
+  not_recommended_for:
+    - feature visibility toggles without policy intent
+  known_limitations:
+    - maturity evidence is registry-external today
+---
+
+# Authorization Policy Evaluation
+
+Policy evaluation from flex-auth sits between identity resolution and protected
+systems.
\ No newline at end of file
diff --git a/registry/capabilities/capability.feature-control.visibility.md b/registry/capabilities/capability.feature-control.visibility.md
new file mode 100644
index 0000000..d658b03
--- /dev/null
+++ b/registry/capabilities/capability.feature-control.visibility.md
@@ -0,0 +1,77 @@
+---
+id: capability.feature-control.visibility
+name: Feature Visibility Control
+summary: Control whether features are visible or hidden for subjects without changing underlying entitlement or authorization.
+owner: feature-control
+status: draft
+domain: helix_forge
+tags: [feature-control, visibility]
+
+maturity:
+  discovery:
+    current: D4
+    target: D5
+    confidence: medium
+    rationale: Bounded as distinct from evaluation and rollout in feature-control domain.
+  availability:
+    current: A2
+    target: A4
+    confidence: low
+    rationale: May share SDK artifacts with evaluate but is not separately exposed as API.
+
+external_evidence:
+  completeness:
+    level: C2
+    name: Partial
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - visibility distinguished from evaluation in registry model
+    broken_expectations:
+      - no standalone visibility API documented separately
+    out_of_scope_expectations:
+      - authorization policy decisions
+  reliability:
+    level: R1
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - easily conflated with evaluate capability
+
+discovery:
+  intent: Govern feature visibility separately from availability evaluation and rollout staging.
+  includes:
+    - hide/show feature UI or capability surfaces
+    - visibility rules per subject context
+  excludes:
+    - entitlement ownership
+    - rollout percentage control
+  use_cases: []
+
+availability:
+  current_level: A2
+  target_level: A4
+  current_artifacts:
+    - feature-control/packages/feature-control-sdk
+  consumption_modes:
+    - source module
+
+relations:
+  depends_on:
+    - capability.feature-control.evaluate
+  related_to:
+    - capability.feature-control.rollout
+
+consumer_guidance:
+  recommended_for:
+    - planning visibility behavior separate from on/off evaluation
+  not_recommended_for:
+    - authorization or billing gating
+  known_limitations:
+    - implementation may be bundled with evaluate SDK today
+---
+
+# Feature Visibility Control
+
+Visibility governs whether a feature surface appears, distinct from whether the
+feature is enabled for a subject.
\ No newline at end of file
diff --git a/registry/capabilities/capability.registry.validate.md b/registry/capabilities/capability.registry.validate.md
new file mode 100644
index 0000000..9f138ae
--- /dev/null
+++ b/registry/capabilities/capability.registry.validate.md
@@ -0,0 +1,88 @@
+---
+id: capability.registry.validate
+name: Registry Entry Validation
+summary: Validate capability registry entries against schema, index consistency, and relation integrity.
+owner: reuse-surface
+status: draft
+domain: helix_forge
+tags: [registry, validation, cli]
+
+maturity:
+  discovery:
+    current: D4
+    target: D5
+    confidence: medium
+    rationale: UC-RS-023 is implemented via reuse-surface validate with schema and drift checks.
+  availability:
+    current: A3
+    target: A3
+    confidence: high
+    rationale: Available as reuse-surface validate CLI command.
+
+external_evidence:
+  completeness:
+    level: C3
+    name: Functional Core
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - schema validation for entry front matter
+      - index drift detection
+      - optional relation integrity checks
+    broken_expectations: []
+    out_of_scope_expectations:
+      - runtime validation of registered capability implementations
+  reliability:
+    level: R2
+    name: Tolerable
+    confidence: medium
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - requires local venv install
+
+discovery:
+  intent: Keep registry data structurally sound so agents and humans can trust discovery metadata.
+  includes:
+    - JSON Schema validation
+    - index drift warnings
+    - relation reference checks
+  excludes:
+    - validating implementation code in other repos
+  use_cases:
+    - UC-RS-023
+  research_memos:
+    - specs/UseCaseCatalog.md
+
+availability:
+  current_level: A3
+  target_level: A3
+  current_artifacts:
+    - reuse_surface/cli.py
+    - schemas/capability.schema.yaml
+  consumption_modes:
+    - cli
+
+relations:
+  depends_on:
+    - capability.registry.register
+  supports: []
+  related_to:
+    - capability.registry.register
+
+evidence:
+  documentation:
+    - tools/README.md
+  tests: []
+
+consumer_guidance:
+  recommended_for:
+    - pre-commit and CI validation of registry changes
+  not_recommended_for:
+    - certifying business correctness of capability claims
+  known_limitations:
+    - warnings do not fail CI unless --fail-on-warnings is set
+---
+
+# Registry Entry Validation
+
+Validates registry shape and consistency through the reuse-surface CLI.
\ No newline at end of file
diff --git a/registry/capabilities/capability.statehub.progress-log.md b/registry/capabilities/capability.statehub.progress-log.md
new file mode 100644
index 0000000..a54bd71
--- /dev/null
+++ b/registry/capabilities/capability.statehub.progress-log.md
@@ -0,0 +1,78 @@
+---
+id: capability.statehub.progress-log
+name: Work Progress Logging
+summary: Record progress events, decisions, and session notes against workstreams and tasks in State Hub.
+owner: state-hub
+status: draft
+domain: helix_forge
+tags: [state-hub, progress, coordination]
+
+maturity:
+  discovery:
+    current: D4
+    target: D5
+    confidence: medium
+    rationale: Progress API and agent session protocol are documented in state-hub AGENTS.md.
+  availability:
+    current: A4
+    target: A6
+    confidence: medium
+    rationale: Available via State Hub HTTP POST /progress/ endpoint.
+
+external_evidence:
+  completeness:
+    level: C3
+    name: Functional Core
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - progress events attach to workstreams
+      - agents can log session summaries
+    broken_expectations: []
+    out_of_scope_expectations:
+      - replacing git commit history
+  reliability:
+    level: R2
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - depends on hub availability
+
+discovery:
+  intent: Provide auditable progress memory for cross-repo agent and operator work.
+  includes:
+    - progress event creation
+    - workstream and task linkage
+    - author attribution
+  excludes:
+    - canonical workplan storage
+  use_cases: []
+
+availability:
+  current_level: A4
+  target_level: A6
+  current_artifacts:
+    - state-hub/api/
+  consumption_modes:
+    - service API
+
+relations:
+  depends_on:
+    - capability.statehub.workstream-coordinate
+  supports: []
+  related_to:
+    - capability.statehub.workstream-coordinate
+
+consumer_guidance:
+  recommended_for:
+    - closing agent sessions with hub progress notes
+  not_recommended_for:
+    - authoritative task status (use workplan files + fix-consistency)
+  known_limitations:
+    - hub must be running locally or via tunnel
+---
+
+# Work Progress Logging
+
+Progress logging complements file-backed workplans with live session memory in
+State Hub.
\ No newline at end of file
diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml
index adfa467..bf5d6d5 100644
--- a/registry/indexes/capabilities.yaml
+++ b/registry/indexes/capabilities.yaml
@@ -1,19 +1,40 @@
 # Manually maintained capability index for humans and agents.
-# Update this file whenever a capability is added, promoted, or deprecated.
 version: 1
 updated: "2026-06-15"
 domain: helix_forge
 capabilities:
-  - id: capability.registry.register
-    name: Capability Registration
-    summary: Register a new capability so it becomes visible for planning and implementation reuse.
-    vector: D3 / A3 / C2 / R2
+  - id: capability.activity.event-coordinate
+    name: Organizational Event Coordination
+    summary: Coordinate structured responses to cross-domain events through activity workflows and automation.
+    vector: D3 / A1 / C1 / R0
     domain: helix_forge
     status: draft
-    owner: reuse-surface
-    path: registry/capabilities/capability.registry.register.md
-    tags: [registry, governance, meta]
-    consumption_modes: [informational, markdown authoring, cli]
+    owner: activity-core
+    path: registry/capabilities/capability.activity.event-coordinate.md
+    tags: [activity, coordination, automation]
+    consumption_modes: [informational]
+
+  - id: capability.audit.event-retain
+    name: Audit Event Retention
+    summary: Collect, normalize, retain, and search audit events with integrity evidence across tenants.
+    vector: D4 / A2 / C2 / R1
+    domain: helix_forge
+    status: draft
+    owner: audit-core
+    path: registry/capabilities/capability.audit.event-retain.md
+    tags: [audit, retention, compliance]
+    consumption_modes: [source module]
+
+  - id: capability.authorization.policy-evaluate
+    name: Authorization Policy Evaluation
+    summary: Evaluate access decisions from policy-as-code rules for subjects, resources, and actions.
+    vector: D4 / A2 / C2 / R1
+    domain: helix_forge
+    status: draft
+    owner: flex-auth
+    path: registry/capabilities/capability.authorization.policy-evaluate.md
+    tags: [authorization, policy, flex-auth]
+    consumption_modes: [source module]
 
   - id: capability.feature-control.evaluate
     name: Feature Availability Evaluation
@@ -28,7 +49,7 @@ capabilities:
 
   - id: capability.feature-control.rollout
     name: Feature Rollout Control
-    summary: Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability.
+    summary: Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules.
     vector: D4 / A2 / C2 / R1
     domain: helix_forge
     status: draft
@@ -37,20 +58,20 @@ capabilities:
     tags: [feature-control, rollout, planning]
     consumption_modes: [source module, SDK]
 
-  - id: capability.identity.vocabulary-canonicalize
-    name: Identity Vocabulary Canonicalization
-    summary: Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
-    vector: D4 / A0 / C2 / R0
+  - id: capability.feature-control.visibility
+    name: Feature Visibility Control
+    summary: Control whether features are visible or hidden for subjects without changing entitlement or authorization.
+    vector: D4 / A2 / C2 / R1
     domain: helix_forge
     status: draft
-    owner: identity-canon
-    path: registry/capabilities/capability.identity.vocabulary-canonicalize.md
-    tags: [identity, terminology, research]
-    consumption_modes: [informational]
+    owner: feature-control
+    path: registry/capabilities/capability.feature-control.visibility.md
+    tags: [feature-control, visibility]
+    consumption_modes: [source module]
 
   - id: capability.identity.subject-resolution
     name: Identity Subject Resolution
-    summary: Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model.
+    summary: Resolve who or what is acting by mapping principals, accounts, actors, and identifiers to a stable subject model.
     vector: D3 / A0 / C1 / R0
     domain: helix_forge
     status: draft
@@ -59,9 +80,53 @@ capabilities:
     tags: [identity, subject, architecture]
     consumption_modes: [informational]
 
+  - id: capability.identity.vocabulary-canonicalize
+    name: Identity Vocabulary Canonicalization
+    summary: Define an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
+    vector: D4 / A0 / C2 / R0
+    domain: helix_forge
+    status: draft
+    owner: identity-canon
+    path: registry/capabilities/capability.identity.vocabulary-canonicalize.md
+    tags: [identity, terminology, research]
+    consumption_modes: [informational]
+
+  - id: capability.registry.register
+    name: Capability Registration
+    summary: Register a new capability so it becomes visible for planning and implementation reuse.
+    vector: D3 / A3 / C2 / R2
+    domain: helix_forge
+    status: draft
+    owner: reuse-surface
+    path: registry/capabilities/capability.registry.register.md
+    tags: [registry, governance, meta]
+    consumption_modes: [informational, markdown authoring, cli]
+
+  - id: capability.registry.validate
+    name: Registry Entry Validation
+    summary: Validate capability registry entries against schema, index consistency, and relation integrity.
+    vector: D4 / A3 / C3 / R2
+    domain: helix_forge
+    status: draft
+    owner: reuse-surface
+    path: registry/capabilities/capability.registry.validate.md
+    tags: [registry, validation, cli]
+    consumption_modes: [cli]
+
+  - id: capability.statehub.progress-log
+    name: Work Progress Logging
+    summary: Record progress events, decisions, and session notes against workstreams and tasks in State Hub.
+    vector: D4 / A4 / C3 / R2
+    domain: helix_forge
+    status: draft
+    owner: state-hub
+    path: registry/capabilities/capability.statehub.progress-log.md
+    tags: [state-hub, progress, coordination]
+    consumption_modes: [service API]
+
   - id: capability.statehub.workstream-coordinate
     name: Workstream And Task Coordination
-    summary: Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service.
+    summary: Track active workstreams, tasks, progress, and consistency across domain repositories.
     vector: D4 / A4 / C3 / R2
     domain: helix_forge
     status: draft
diff --git a/registry/indexes/federated.yaml b/registry/indexes/federated.yaml
index 5b3aac4..e6c9589 100644
--- a/registry/indexes/federated.yaml
+++ b/registry/indexes/federated.yaml
@@ -7,8 +7,59 @@ collision_policy: warn
 sources:
 - repo: reuse-surface
   index: registry/indexes/capabilities.yaml
-  count: 6
+  count: 12
 capabilities:
+- id: capability.activity.event-coordinate
+  name: Organizational Event Coordination
+  summary: Coordinate structured responses to cross-domain events through activity
+    workflows and automation.
+  vector: D3 / A1 / C1 / R0
+  domain: helix_forge
+  status: draft
+  owner: activity-core
+  path: registry/capabilities/capability.activity.event-coordinate.md
+  tags:
+  - activity
+  - coordination
+  - automation
+  consumption_modes:
+  - informational
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.audit.event-retain
+  name: Audit Event Retention
+  summary: Collect, normalize, retain, and search audit events with integrity evidence
+    across tenants.
+  vector: D4 / A2 / C2 / R1
+  domain: helix_forge
+  status: draft
+  owner: audit-core
+  path: registry/capabilities/capability.audit.event-retain.md
+  tags:
+  - audit
+  - retention
+  - compliance
+  consumption_modes:
+  - source module
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.authorization.policy-evaluate
+  name: Authorization Policy Evaluation
+  summary: Evaluate access decisions from policy-as-code rules for subjects, resources,
+    and actions.
+  vector: D4 / A2 / C2 / R1
+  domain: helix_forge
+  status: draft
+  owner: flex-auth
+  path: registry/capabilities/capability.authorization.policy-evaluate.md
+  tags:
+  - authorization
+  - policy
+  - flex-auth
+  consumption_modes:
+  - source module
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
 - id: capability.feature-control.evaluate
   name: Feature Availability Evaluation
   summary: Evaluate whether a feature is active, hidden, disabled, or unavailable
@@ -30,7 +81,7 @@ capabilities:
 - id: capability.feature-control.rollout
   name: Feature Rollout Control
   summary: Gradually expose features to subjects across tenants, domains, groups,
-    or cohorts using rollout rules and staged availability.
+    or cohorts using rollout rules.
   vector: D4 / A2 / C2 / R1
   domain: helix_forge
   status: draft
@@ -45,10 +96,26 @@ capabilities:
   - SDK
   source_repo: reuse-surface
   source_index: registry/indexes/capabilities.yaml
+- id: capability.feature-control.visibility
+  name: Feature Visibility Control
+  summary: Control whether features are visible or hidden for subjects without changing
+    entitlement or authorization.
+  vector: D4 / A2 / C2 / R1
+  domain: helix_forge
+  status: draft
+  owner: feature-control
+  path: registry/capabilities/capability.feature-control.visibility.md
+  tags:
+  - feature-control
+  - visibility
+  consumption_modes:
+  - source module
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
 - id: capability.identity.subject-resolution
   name: Identity Subject Resolution
-  summary: Resolve who or what is acting in a context by mapping principals, accounts,
-    actors, and identifiers to a stable subject model.
+  summary: Resolve who or what is acting by mapping principals, accounts, actors,
+    and identifiers to a stable subject model.
   vector: D3 / A0 / C1 / R0
   domain: helix_forge
   status: draft
@@ -64,8 +131,8 @@ capabilities:
   source_index: registry/indexes/capabilities.yaml
 - id: capability.identity.vocabulary-canonicalize
   name: Identity Vocabulary Canonicalization
-  summary: Define and maintain an implementation-neutral vocabulary for identity-related
-    concepts across overlapping domains.
+  summary: Define an implementation-neutral vocabulary for identity-related concepts
+    across overlapping domains.
   vector: D4 / A0 / C2 / R0
   domain: helix_forge
   status: draft
@@ -98,10 +165,44 @@ capabilities:
   - cli
   source_repo: reuse-surface
   source_index: registry/indexes/capabilities.yaml
+- id: capability.registry.validate
+  name: Registry Entry Validation
+  summary: Validate capability registry entries against schema, index consistency,
+    and relation integrity.
+  vector: D4 / A3 / C3 / R2
+  domain: helix_forge
+  status: draft
+  owner: reuse-surface
+  path: registry/capabilities/capability.registry.validate.md
+  tags:
+  - registry
+  - validation
+  - cli
+  consumption_modes:
+  - cli
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.statehub.progress-log
+  name: Work Progress Logging
+  summary: Record progress events, decisions, and session notes against workstreams
+    and tasks in State Hub.
+  vector: D4 / A4 / C3 / R2
+  domain: helix_forge
+  status: draft
+  owner: state-hub
+  path: registry/capabilities/capability.statehub.progress-log.md
+  tags:
+  - state-hub
+  - progress
+  - coordination
+  consumption_modes:
+  - service API
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
 - id: capability.statehub.workstream-coordinate
   name: Workstream And Task Coordination
   summary: Track active workstreams, tasks, progress, and consistency across domain
-    repositories through a local-first coordination service.
+    repositories.
   vector: D4 / A4 / C3 / R2
   domain: helix_forge
   status: draft
diff --git a/reuse_surface/catalog.py b/reuse_surface/catalog.py
index 2bb3a35..d169233 100644
--- a/reuse_surface/catalog.py
+++ b/reuse_surface/catalog.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import html
+import json
 from collections import defaultdict
 from pathlib import Path
 from typing import Any
@@ -9,6 +10,9 @@ ROOT = Path(__file__).resolve().parent.parent
 CATALOG_MD = ROOT / "docs" / "CapabilityCatalog.md"
 CATALOG_HTML_DIR = ROOT / "docs" / "catalog"
 CATALOG_HTML = CATALOG_HTML_DIR / "index.html"
+CATALOG_JSON = CATALOG_HTML_DIR / "registry.json"
+CATALOG_SEARCH = CATALOG_HTML_DIR / "search.html"
+GRAPH_HTML = ROOT / "docs" / "graph" / "index.html"
 
 
 def _grouped_capabilities(
@@ -112,11 +116,105 @@ def render_html(
 """
 
 
+def render_search_html() -> str:
+    return """
+
+
+  
+  Capability Catalog Search
+  
+
+
+  
Capability Catalog

+  
Client-side search over registry.json. Generated by reuse-surface catalog.

+  
+  

+  

+  
+
+
+"""
+
+
+def render_graph_explorer(mermaid_source: str) -> str:
+    escaped = json.dumps(mermaid_source)
+    return f"""
+
+
+  
+  Capability Relation Graph
+  
+  
+
+
+  
Capability Relation Graph

+  
Generated from entry relations fields. Regenerate with reuse-surface graph.

+  

+  
+
+
+"""
+
+
 def write_catalog(
     index: dict[str, Any],
     indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]],
-) -> tuple[Path, Path]:
+    *,
+    mermaid_source: str | None = None,
+) -> list[Path]:
     CATALOG_HTML_DIR.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
     CATALOG_MD.write_text(render_markdown(index, indexed_entries), encoding="utf-8")
+    written.append(CATALOG_MD)
     CATALOG_HTML.write_text(render_html(index, indexed_entries), encoding="utf-8")
-    return CATALOG_MD, CATALOG_HTML
\ No newline at end of file
+    written.append(CATALOG_HTML)
+    payload = {
+        "domain": index.get("domain"),
+        "updated": index.get("updated"),
+        "capabilities": [item for item, _ in indexed_entries],
+    }
+    CATALOG_JSON.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    written.append(CATALOG_JSON)
+    CATALOG_SEARCH.write_text(render_search_html(), encoding="utf-8")
+    written.append(CATALOG_SEARCH)
+    if mermaid_source is not None:
+        GRAPH_HTML.parent.mkdir(parents=True, exist_ok=True)
+        GRAPH_HTML.write_text(render_graph_explorer(mermaid_source), encoding="utf-8")
+        written.append(GRAPH_HTML)
+    return written
\ No newline at end of file
diff --git a/reuse_surface/cli.py b/reuse_surface/cli.py
index 62e9b6e..4e983d0 100644
--- a/reuse_surface/cli.py
+++ b/reuse_surface/cli.py
@@ -64,7 +64,7 @@ def cmd_validate(args: argparse.Namespace) -> int:
     for error in errors:
         print(f"error: {error}", file=sys.stderr)
 
-    if errors:
+    if errors or (args.fail_on_warnings and warnings):
         return 1
     print(f"ok: validated {len(paths)} capability entr{'y' if len(paths) == 1 else 'ies'}")
     return 0
@@ -167,18 +167,27 @@ def cmd_graph(args: argparse.Namespace) -> int:
         print(content, end="")
     else:
         path = write_graph()
+        from reuse_surface.catalog import GRAPH_HTML, render_graph_explorer
+
+        GRAPH_HTML.parent.mkdir(parents=True, exist_ok=True)
+        GRAPH_HTML.write_text(render_graph_explorer(content), encoding="utf-8")
         print(f"ok: wrote {path.relative_to(ROOT)}")
+        print(f"ok: wrote {GRAPH_HTML.relative_to(ROOT)}")
     for warning in warnings:
         print(f"warning: {warning}", file=sys.stderr)
+    if args.fail_on_warnings and warnings:
+        return 1
     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)}")
+    paths = write_catalog(
+        index, indexed_entries, mermaid_source=render_mermaid()
+    )
+    for path in paths:
+        print(f"ok: wrote {path.relative_to(ROOT)}")
     return 0
 
 
@@ -237,6 +246,11 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="check relation cycles and broken references",
     )
+    validate.add_argument(
+        "--fail-on-warnings",
+        action="store_true",
+        help="exit non-zero when warnings are present",
+    )
     validate.set_defaults(func=cmd_validate)
 
     federation = subparsers.add_parser(
@@ -290,6 +304,11 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="report depends_on cycles and broken relation references",
     )
+    graph.add_argument(
+        "--fail-on-warnings",
+        action="store_true",
+        help="exit non-zero when relation warnings are present",
+    )
     graph.set_defaults(func=cmd_graph)
 
     args = parser.parse_args(argv)
diff --git a/tests/test_registry.py b/tests/test_registry.py
new file mode 100644
index 0000000..458786b
--- /dev/null
+++ b/tests/test_registry.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-m", "reuse_surface.cli", *args],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_validate_passes():
+    result = run_cli("validate")
+    assert result.returncode == 0
+    assert "ok: validated" in result.stdout
+
+
+def test_validate_relations_clean():
+    result = run_cli("validate", "--relations", "--fail-on-warnings")
+    assert result.returncode == 0, result.stderr
+
+
+def test_query_finds_registry():
+    result = run_cli("query", "--tag", "registry")
+    assert result.returncode == 0
+    assert "capability.registry.register" in result.stdout
+
+
+def test_federation_compose():
+    result = run_cli("federation", "compose")
+    assert result.returncode == 0
+    assert (ROOT / "registry/indexes/federated.yaml").exists()
+
+
+def test_export_json():
+    result = run_cli("export", "--format", "json")
+    assert result.returncode == 0
+    assert '"capabilities"' in result.stdout
+
+
+def test_graph_check_clean():
+    result = run_cli("graph", "--check", "--fail-on-warnings")
+    assert result.returncode == 0, result.stderr
+
+
+def test_catalog_writes_search():
+    result = run_cli("catalog")
+    assert result.returncode == 0
+    assert (ROOT / "docs/catalog/registry.json").exists()
+    assert (ROOT / "docs/catalog/search.html").exists()
\ No newline at end of file
diff --git a/tools/README.md b/tools/README.md
index bce65ee..a5cd6a2 100644
--- a/tools/README.md
+++ b/tools/README.md
@@ -59,7 +59,8 @@ Generate human-readable catalog artifacts (UC-RS-018).
 reuse-surface catalog
 ```
 
-Writes `docs/CapabilityCatalog.md` and `docs/catalog/index.html`.
+Writes `docs/CapabilityCatalog.md`, `docs/catalog/index.html`,
+`docs/catalog/registry.json`, and `docs/catalog/search.html`.
 
 ### federation compose
 
@@ -81,6 +82,8 @@ reuse-surface graph --check
 reuse-surface graph --stdout
 ```
 
+Writes `docs/graph/capability-graph.mmd` and `docs/graph/index.html`.
+
 ## Export format
 
 The export bundle includes:
diff --git a/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md b/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md
new file mode 100644
index 0000000..346424b
--- /dev/null
+++ b/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md
@@ -0,0 +1,78 @@
+---
+id: REUSE-WP-0006
+type: workplan
+title: "Registry hygiene and coverage expansion"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "d3d0b3ae-dedc-48bc-a6d2-16975e10acc3"
+---
+
+# Registry hygiene and coverage expansion
+
+Close broken relation references, register missing adjacent capabilities, and
+expand helix_forge registry coverage so `reuse-surface graph --check` and
+`validate --relations` run clean.
+
+## Register Missing Relation Targets
+
+```task
+id: REUSE-WP-0006-T01
+status: done
+priority: high
+state_hub_task_id: "183b42ae-7773-484f-afe7-4966e26f1768"
+```
+
+Register three capabilities referenced by existing relations but not yet in the
+index:
+
+- `capability.registry.validate`
+- `capability.feature-control.visibility`
+- `capability.statehub.progress-log`
+
+Each entry must pass validation and appear in the index.
+
+## Expand helix_forge Coverage
+
+```task
+id: REUSE-WP-0006-T02
+status: done
+priority: high
+state_hub_task_id: "3c6b4e4a-07c0-4a06-a64b-f152f8bdb35d"
+```
+
+Register at least three additional helix_forge capabilities from adjacent repos:
+
+- `capability.authorization.policy-evaluate` (flex-auth)
+- `capability.activity.event-coordinate` (activity-core)
+- `capability.audit.event-retain` (audit-core)
+
+Illustrate distinct vectors and link relations where appropriate.
+
+## Regenerate Derived Artifacts
+
+```task
+id: REUSE-WP-0006-T03
+status: done
+priority: medium
+state_hub_task_id: "417e7a0d-2bdd-43fd-8604-3d48cc1fc083"
+```
+
+Run and commit outputs from `federation compose`, `graph`, `catalog`, and
+`export`. Confirm `validate --relations` reports no broken references.
+
+## Update Documentation
+
+```task
+id: REUSE-WP-0006-T04
+status: done
+priority: medium
+state_hub_task_id: "9e061f46-5de8-4cf7-a7f1-b0e886391b7d"
+```
+
+Update `SCOPE.md` capability inventory and `docs/IntentScopeGapAnalysis.md`
+self-assessment after coverage growth.
\ No newline at end of file
diff --git a/workplans/REUSE-WP-0007-interactive-catalog.md b/workplans/REUSE-WP-0007-interactive-catalog.md
new file mode 100644
index 0000000..02daebd
--- /dev/null
+++ b/workplans/REUSE-WP-0007-interactive-catalog.md
@@ -0,0 +1,54 @@
+---
+id: REUSE-WP-0007
+type: workplan
+title: "Interactive capability catalog"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "1afa1322-7d60-41aa-bf7e-3ef29bb4d3a5"
+---
+
+# Interactive capability catalog
+
+Close gap analysis priority 13 (UC-RS-018 enhancement). Build a static,
+searchable catalog UI over exported registry data.
+
+## Add Catalog Site Generator
+
+```task
+id: REUSE-WP-0007-T01
+status: done
+priority: high
+state_hub_task_id: "84c56268-2e0b-42e6-b20e-6fbf059dcc20"
+```
+
+Extend `reuse-surface catalog` (or add `catalog site`) to emit
+`docs/catalog/registry.json` alongside existing MD/HTML outputs.
+
+## Build Searchable Catalog UI
+
+```task
+id: REUSE-WP-0007-T02
+status: done
+priority: high
+state_hub_task_id: "d587bc50-adb2-424a-a9d3-600a2ec5ba9b"
+```
+
+Create `docs/catalog/search.html` with client-side filter by name, summary, tags,
+vector, and consumption mode. No backend required.
+
+## Wire Catalog Into CI And Docs
+
+```task
+id: REUSE-WP-0007-T03
+status: done
+priority: medium
+state_hub_task_id: "eca7438c-3c2f-4027-9b40-67df5f17aca7"
+```
+
+Update CI to regenerate catalog artifacts, document browsing in
+`docs/CapabilityRegistryConcept.md` and `SCOPE.md`.
\ No newline at end of file
diff --git a/workplans/REUSE-WP-0008-graph-explorer.md b/workplans/REUSE-WP-0008-graph-explorer.md
new file mode 100644
index 0000000..0b83307
--- /dev/null
+++ b/workplans/REUSE-WP-0008-graph-explorer.md
@@ -0,0 +1,42 @@
+---
+id: REUSE-WP-0008
+type: workplan
+title: "Interactive relation graph explorer"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "63f8a2da-d179-4875-8cff-40a0fa2ca067"
+---
+
+# Interactive relation graph explorer
+
+Close gap analysis priority 16. Provide a browsable HTML view of
+`docs/graph/capability-graph.mmd` for architects (UC-RS-016).
+
+## Add Graph Explorer Page
+
+```task
+id: REUSE-WP-0008-T01
+status: done
+priority: high
+state_hub_task_id: "2d08de47-d3c0-484f-a945-9691da9688e4"
+```
+
+Create `docs/graph/index.html` that renders the Mermaid graph in-browser with
+node labels and a legend for relation types.
+
+## Integrate Graph Generation
+
+```task
+id: REUSE-WP-0008-T02
+status: done
+priority: medium
+state_hub_task_id: "ada96492-88d0-438e-8d2b-ae0fdd8abb06"
+```
+
+Ensure `reuse-surface graph` documents and regenerates both `.mmd` and the
+explorer page dependency. Update `registry/README.md` and `AGENTS.md`.
\ No newline at end of file
diff --git a/workplans/REUSE-WP-0009-cli-hardening.md b/workplans/REUSE-WP-0009-cli-hardening.md
new file mode 100644
index 0000000..8d4379b
--- /dev/null
+++ b/workplans/REUSE-WP-0009-cli-hardening.md
@@ -0,0 +1,55 @@
+---
+id: REUSE-WP-0009
+type: workplan
+title: "CLI hardening and test suite"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "9121d16f-879f-4db3-9df6-06f7543481d8"
+---
+
+# CLI hardening and test suite
+
+Raise registry tooling reliability toward R3 with automated tests and stricter
+CI gates after WP-0006 relation hygiene.
+
+## Add pytest Suite
+
+```task
+id: REUSE-WP-0009-T01
+status: done
+priority: high
+state_hub_task_id: "57d0869a-38bb-409a-b5b1-b3c73ff31a96"
+```
+
+Add `tests/` covering validate, query, export, overlaps, federation compose,
+graph, and catalog commands. Add `[dev]` optional deps and document
+`.venv/bin/pytest` in `AGENTS.md`.
+
+## Add Fail-On-Warnings Flags
+
+```task
+id: REUSE-WP-0009-T02
+status: done
+priority: high
+state_hub_task_id: "d10fde06-e09b-4292-b6c8-ced5e5ef213c"
+```
+
+Add `--fail-on-warnings` to `validate` and `graph --check`. Use in CI once
+WP-0006 relation hygiene is complete.
+
+## Tighten CI Pipeline
+
+```task
+id: REUSE-WP-0009-T03
+status: done
+priority: medium
+state_hub_task_id: "79c0fa70-7ec1-4762-9a7c-9783f0997016"
+```
+
+Update `.gitea/workflows/ci.yml` to run pytest and fail on relation warnings.
+Record reliability evidence on `capability.registry.register`.
\ No newline at end of file
diff --git a/workplans/REUSE-WP-0010-network-federation.md b/workplans/REUSE-WP-0010-network-federation.md
new file mode 100644
index 0000000..e567572
--- /dev/null
+++ b/workplans/REUSE-WP-0010-network-federation.md
@@ -0,0 +1,54 @@
+---
+id: REUSE-WP-0010
+type: workplan
+title: "Network federation for remote indexes"
+domain: helix_forge
+repo: reuse-surface
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "da812165-d56e-47fa-9901-bb3747522ec4"
+---
+
+# Network federation for remote indexes
+
+Close gap analysis priority 15. Extend federation beyond filesystem paths to
+fetch capability indexes from HTTP URLs or git raw endpoints.
+
+## Extend Federation Schema For URLs
+
+```task
+id: REUSE-WP-0010-T01
+status: todo
+priority: medium
+state_hub_task_id: "6f181057-e0f7-4879-9eb9-928a527a01ee"
+```
+
+Extend `schemas/federation.schema.yaml` and manifest format to support `url`
+sources alongside `index` file paths, with optional auth and TTL metadata.
+
+## Implement Remote Index Fetch
+
+```task
+id: REUSE-WP-0010-T02
+status: todo
+priority: medium
+state_hub_task_id: "a2fac7d5-9383-4a42-bd23-3e8dbc7d550b"
+```
+
+Add HTTP fetch to `federation compose` with local cache under
+`registry/federation/cache/`. Clear errors when remote source unavailable.
+
+## Document Federation Operations
+
+```task
+id: REUSE-WP-0010-T03
+status: todo
+priority: low
+state_hub_task_id: "73996193-ecae-4fb4-84f7-fe84a5cd8898"
+```
+
+Update `docs/RegistryFederation.md` with remote source examples and agent
+guidance for cross-repo discovery without local checkout.
\ No newline at end of file