diff --git a/AGENTS.md b/AGENTS.md index 9fa4f5a..0875cb5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -101,6 +101,136 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ --- +## Local Developer Workflow + +This repository is currently documentation-only. There is no package manifest, +runtime application, build system, executable test suite, or formatter/linter +configuration checked in. + +### Install + +No install step is required for normal repository work. + +### Build + +No build step exists. Treat Markdown, YAML, and workplan edits as source +artifacts. + +### Test / lint + +There is no project test runner or markdown linter configured yet. Use these +checks before closing a change: + +```bash +# Confirm the repository file inventory still looks intentional +rg --files + +# Catch whitespace errors in tracked and staged diffs +git diff --check +``` + +When workplan files change, sync ADR-001 file state into State Hub: + +```bash +curl -s -X POST "http://127.0.0.1:8000/repos/reuse-surface/sync?fix=true" \ + | python3 -m json.tool +``` + +If the HTTP sync endpoint is unavailable, run the consistency script from the +State Hub checkout: + +```bash +cd ~/state-hub +.venv/bin/python scripts/consistency_check.py --repo reuse-surface --fix +.venv/bin/python scripts/consistency_check.py --repo reuse-surface +``` + +The generated instruction in older workplans says `make fix-consistency +REPO=reuse-surface`; that is still valid when `uv` is installed and on PATH. +On this workstation, the `.venv/bin/python` fallback has been verified. + +### Run + +There is no local service to run from this repository. + +### Documentation Review Checklist + +- Keep `INTENT.md`, `SCOPE.md`, and `specs/` aligned on the registry-first + reuse boundary. +- Keep maturity definitions in `specs/CapabilityMaturityStandard.md` consistent + with `INTENT.md` and `specs/ProductRequirementsDocument.md`. +- Keep registry entries, indexes, and schemas in `registry/`, `schemas/`, and + `templates/` current when capabilities change. +- Record implementation ideas in workplans, not as premature runtime code in + this repository. + +--- + +## Capability Registry + +Before building or documenting a new reusable behavior, query the registry to +avoid duplication and to select the best existing capability for planning or +implementation reuse. + +### Orient + +```bash +# Fast discovery surface — read this first +cat registry/indexes/capabilities.yaml + +# Authoring template and schema +cat templates/capability-entry.template.md +cat schemas/capability.schema.yaml + +# Validation and search guidance +cat registry/README.md +cat tools/README.md +``` + +### Query workflow + +1. Read `registry/indexes/capabilities.yaml`. +2. Filter by `vector`, `tags`, `consumption_modes`, `domain`, or `summary`. +3. Open only matching files under `registry/capabilities/`. +4. Compare candidates using `discovery`, `external_evidence`, `availability`, + and `relations` from the entry front matter. +5. Prefer planning reuse when discovery is strong (`D3+`, especially `D5+`). +6. Prefer implementation reuse only when availability is consumable (`A2+` code, + `A3+` CLI, `A4+` API/SDK). + +### Add a new capability + +1. Search the index for overlap (UC-RS-015) before creating a new entry. +2. Copy `templates/capability-entry.template.md` to + `registry/capabilities/capability...md`. +3. Start at `D0 / A0 / C0 / R0` when evidence is minimal; keep gaps explicit. +4. Add the entry to `registry/indexes/capabilities.yaml`. +5. Run the manual validation checklist in `registry/README.md`. + +### Promote a capability + +1. Attach evidence required by `specs/CapabilityMaturityStandard.md` for the + target level. +2. Update `maturity` for discovery/availability and `external_evidence` for + completeness/reliability separately. +3. Refresh the index `vector` and record rationale in the entry body. +4. Do not treat higher availability as proof of reliability or completeness. + +### MVP acceptance mapping + +| Acceptance criterion | Registry surface | +|---|---| +| Add D0/A0/C0/R0 with minimal friction | template + index + registry README | +| Promote through discovery levels | entry front matter + maturity standard | +| Identify current consumption mode | `availability` + index `consumption_modes` | +| Record expectations and broken expectations | `external_evidence.completeness` | +| Record reliability evidence | `external_evidence.reliability` | +| Search by maturity and availability | `indexes/capabilities.yaml` filters | +| Compare candidates | entry vectors + relations + README guidance | +| Avoid duplicate capabilities | index search before add | + +--- + ## Workplan Convention (ADR-001) Work items originate as files in this repo — not in the hub. The hub is a diff --git a/SCOPE.md b/SCOPE.md index dfe55ee..1554b9c 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,32 +1,53 @@ # SCOPE -> This file was generated by `statehub register`. Refine it as the repository -> boundaries become clearer. - ## One-liner Capability registry for planning and implementation reuse based on discovery and delivery maturity. ## Core Idea -reuse-surface exists to provide the capability described in INTENT.md. +`reuse-surface` provides a registry-centric reuse layer for capabilities. It +makes capabilities visible, comparable, assessable, and reusable for planning, +implementation, and operation. A capability that is not registered is invisible +for reuse within this product boundary. ## In Scope -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. +- Maintain the capability maturity model, standards, schemas, registry formats, + examples, indexes, validation guidance, and agent instructions. +- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans + aligned on the registry-first reuse boundary. +- Support humans and agents as registry consumers through Markdown-first + authoring and machine-readable metadata. +- Record decisions, progress, and workplan status through State Hub. +- Verify changes with documentation review, `git diff --check`, and ADR-001 + consistency checks. ## Out of Scope -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. +- Host or operate the registered capabilities themselves. +- Replace package registries, service catalogs, issue trackers, or project + management systems. +- Judge internal code quality as capability maturity. +- Own unrelated adjacent systems or make irreversible operational decisions + without human approval. ## Current State -- Status: active; implementation and stability should be verified by the repo agent. +- Status: active specification scaffold. +- The repository is currently documentation-only. It has no package manifest, + build system, runtime app, or executable test suite. +- `specs/` contains the product requirements, use case catalog, and capability + maturity standard. `INTENT.md` defines the registry model and guiding + principles. +- `registry/`, `schemas/`, `templates/`, and `tools/` contain the MVP registry + foundation seeded by `REUSE-WP-0002`. ## Getting Oriented - Start with: INTENT.md +- Product requirements: specs/ProductRequirementsDocument.md +- Use cases: specs/UseCaseCatalog.md +- Maturity standard: specs/CapabilityMaturityStandard.md - Agent instructions: AGENTS.md -- Workplans: workplans/ +- Workplans: workplans/ \ No newline at end of file diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 0000000..afd59b2 --- /dev/null +++ b/registry/README.md @@ -0,0 +1,136 @@ +# Capability Registry + +Markdown-first registry for reusable capabilities in the helix_forge domain. + +## Layout + +```text +registry/ +├── README.md +├── capabilities/ +│ └── capability...md +└── indexes/ + └── capabilities.yaml +``` + +- **Entries** live in `capabilities/` as Markdown files with YAML front matter. +- **Index** at `indexes/capabilities.yaml` is the fast discovery surface for + humans and agents. +- **Schema** at `schemas/capability.schema.yaml` defines required front matter. +- **Template** at `templates/capability-entry.template.md` is the authoring + starting point. + +## Add a new capability (D0/A0/C0/R0) + +1. Copy `templates/capability-entry.template.md` to + `registry/capabilities/capability...md`. +2. Set `id`, `name`, `summary`, `owner`, and `status: draft`. +3. Initialize all four dimensions explicitly: + - `maturity.discovery.current: D0` + - `maturity.availability.current: A0` + - `external_evidence.completeness.level: C0` + - `external_evidence.reliability.level: R0` +4. Add the entry to `registry/indexes/capabilities.yaml`. +5. Run the manual validation checklist below. + +Missing evidence is acceptable in the MVP when it is explicit rather than hidden. + +## Manual validation checklist + +Use this checklist until an automated CLI validator exists. + +### Required fields + +- [ ] `id` matches `^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$` +- [ ] `name`, `summary`, `owner`, and `status` are present +- [ ] `maturity.discovery` and `maturity.availability` include `current` and `target` +- [ ] `external_evidence.completeness.level` and `external_evidence.reliability.level` are present +- [ ] Completeness and reliability are **not** nested under `maturity` + +### Enum checks + +Discovery levels: `D0`–`D7` +Availability levels: `A0`–`A7` +Completeness levels: `C0`–`C6` +Reliability levels: `R0`–`R6` +Entry status: `draft`, `reviewed`, `approved`, `deprecated` +Confidence: `low`, `medium`, `high` + +Definitions live in `specs/CapabilityMaturityStandard.md`. + +### Relation checks + +- [ ] Every relation target uses a valid capability ID format +- [ ] Referenced capabilities exist in the index or are explicitly marked as external/planned +- [ ] Cycles in `depends_on` are intentional and documented + +### Index checks + +- [ ] New entry appears in `indexes/capabilities.yaml` +- [ ] `path` points to the correct Markdown file +- [ ] `vector` matches the entry's current maturity levels + +## Search and filter guidance + +### UC-RS-004 — Search by planning need + +1. Read `indexes/capabilities.yaml` and scan `summary`, `tags`, and `vector`. +2. Open candidate entries and review `discovery.intent`, `discovery.use_cases`, + and `discovery.includes`. +3. Prefer entries with discovery `D3+` for roadmap work and `D5+` for MVP + selection. + +Example filter: + +```yaml +discovery: + minimum: D4 +tags: + - identity +``` + +### UC-RS-005 — Search by consumption mode + +1. Filter the index by `consumption_modes` or availability level. +2. Open entries and inspect `availability.current_artifacts`. +3. Treat `A0` entries as planning-only; require `A2+` for code reuse and `A3+` + for automation. + +Example filter: + +```yaml +availability: + minimum: A3 +consumption_modes: + - cli +``` + +### UC-RS-006 — Compare capability candidates + +Compare vectors side by side and read: + +- `discovery.includes` / `discovery.excludes` for overlap +- `external_evidence.completeness` for expectation fit +- `external_evidence.reliability` for consumer risk +- `relations` for dependency and duplication signals + +### UC-RS-015 — Detect duplicate or overlapping capabilities + +Check for overlap in: + +- similar `name` or `summary` +- shared `discovery.includes` +- `relations.related_to` without clear specialization +- duplicate tags and consumption modes with weak boundary differences + +When overlap is real, link entries with `relations.related_to`, `specializes`, +or `generalizes` rather than creating silent duplicates. + +## Promote a capability + +1. Attach evidence appropriate to the target level in + `specs/CapabilityMaturityStandard.md`. +2. Update `maturity` and/or `external_evidence` with rationale and confidence. +3. Update `availability.current_artifacts` when a new consumption mode appears. +4. Refresh the index `vector` and run the validation checklist. +5. Set `status: reviewed` or `approved` when an assessor validates the entry. \ No newline at end of file diff --git a/registry/capabilities/capability.feature-control.evaluate.md b/registry/capabilities/capability.feature-control.evaluate.md new file mode 100644 index 0000000..afa16b7 --- /dev/null +++ b/registry/capabilities/capability.feature-control.evaluate.md @@ -0,0 +1,138 @@ +--- +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. +owner: feature-control +status: draft +domain: helix_forge +tags: + - feature-control + - evaluation + - sdk + +maturity: + discovery: + current: D5 + target: D7 + confidence: medium + rationale: > + Concrete use cases and research references are documented in the maturity + standard example and feature-control domain work. + availability: + current: A4 + target: A6 + confidence: medium + rationale: > + SDK and service API artifacts exist in the feature-control repository. + Managed platform operation is the natural target for multi-tenant reuse. + +external_evidence: + completeness: + level: C3 + name: Functional Core + confidence: medium + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - tenant-level feature evaluation + - user-level feature evaluation + - machine-readable decision result + broken_expectations: + - no agent-specific rule simulation + - no bulk import/export of rules + out_of_scope_expectations: + - billing entitlement ownership + - authorization policy enforcement + reliability: + level: R3 + name: Usable + confidence: medium + basis: consumer_quality_signals + known_reliability_risks: + - unclear timeout behavior under heavy load + - limited diagnostics for complex tenant rule conflicts + +discovery: + intent: > + Support controlled feature availability across installations, tenants, + domains, groups, users, and agents. + includes: + - feature decision evaluation + - context-aware targeting + - explainable decision result + excludes: + - user authorization + - billing entitlement ownership + - UI rendering + assumptions: + - subject and tenant context can be resolved by adjacent capabilities + use_cases: + - ucc.feature-control.tenant-toggle + - ucc.feature-control.agent-disable + - ucc.feature-control.domain-rollout + research_memos: + - specs/CapabilityMaturityStandard.md + +availability: + current_level: A4 + target_level: A6 + current_artifacts: + - feature-control/packages/feature-control-sdk + - feature-control/services/feature-control-api + target_artifacts: + - feature-control/charts/feature-control + - feature-control/platform/feature-control-service + consumption_modes: + - SDK + - service API + - managed platform service + +relations: + depends_on: + - capability.identity.vocabulary-canonicalize + supports: + - capability.registry.register + related_to: + - capability.feature-control.rollout + - capability.feature-control.visibility + +evidence: + documentation: + - specs/CapabilityMaturityStandard.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - application integration through SDK or service API + - tenant-aware feature gating in helix_forge products + not_recommended_for: + - authorization decisions + - billing entitlement ownership + - assuming agent-specific simulation without checking current scope + known_limitations: + - bulk rule management is not yet covered + - agent-specific simulation remains a known gap +--- + +# Feature Availability Evaluation + +## Overview + +This capability evaluates whether a feature should be available for a subject in +a given context. It is the primary implementation-ready example in the sample +registry and demonstrates a D5/A4/C3/R3 vector. + +## Current reuse mode + +Consumers can integrate through SDK or service API artifacts in the +feature-control repository. This is implementation reuse (A4), not just planning +metadata. + +## Comparison notes + +Compared with `capability.registry.register`, this entry is far stronger on +availability and external evidence. Compared with +`capability.identity.vocabulary-canonicalize`, it is stronger on delivery mode +and weaker on cross-domain generalization. \ No newline at end of file diff --git a/registry/capabilities/capability.identity.vocabulary-canonicalize.md b/registry/capabilities/capability.identity.vocabulary-canonicalize.md new file mode 100644 index 0000000..1ead200 --- /dev/null +++ b/registry/capabilities/capability.identity.vocabulary-canonicalize.md @@ -0,0 +1,136 @@ +--- +id: capability.identity.vocabulary-canonicalize +name: Identity Vocabulary Canonicalization +summary: Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains. +owner: identity-canon +status: draft +domain: helix_forge +tags: + - identity + - terminology + - research + +maturity: + discovery: + current: D4 + target: D6 + confidence: medium + rationale: > + identity-canon has researched overlapping terminology across IAM, + directory, federation, and authorization domains, but use-case saturation + is not yet demonstrated. + availability: + current: A0 + target: A2 + confidence: medium + rationale: > + The capability is available as research and canon documentation only. + Future source modules or libraries could raise availability to A2. + +external_evidence: + completeness: + level: C2 + name: Partial + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - draft canonical glossary exists + - terminology conflict map exists + - conceptual model and scenario tests exist + broken_expectations: + - individual source notes are not fully backfilled + - many mappings remain candidate rather than finalized + out_of_scope_expectations: + - operating identity providers + - provisioning or authorization engines + reliability: + level: R0 + confidence: low + basis: consumer_quality_signals + known_reliability_risks: + - draft canon terms may change as source evidence is backfilled + +discovery: + intent: > + Provide a reusable planning primitive for identity vocabulary so architects + and agents can compare overlapping terms consistently without collapsing + product-specific meanings into one ambiguous label. + includes: + - canonical glossary maintenance + - terminology conflict mapping + - conceptual model and scenario tests + - research corpus indexing + excludes: + - identity provider implementation + - account lifecycle services + - authorization policy enforcement + assumptions: + - external product mappings remain separate from canonical definitions + use_cases: + - UC-RS-004 + - UC-RS-006 + research_memos: + - identity-canon/ResearchProposal.md + - identity-canon/canon/CanonicalGlossary.md + +availability: + current_level: A0 + target_level: A2 + current_artifacts: + - identity-canon/canon/CanonicalGlossary.md + - identity-canon/terminology/TerminologyConflictMap.md + - identity-canon/model/ConceptualModel.md + target_artifacts: + - identity-canon/packages/identity-vocabulary + consumption_modes: + - informational + - markdown research artifacts + +relations: + depends_on: [] + supports: + - capability.feature-control.evaluate + - capability.registry.register + related_to: + - capability.identity.subject-resolution + +evidence: + documentation: + - identity-canon/INTENT.md + - identity-canon/canon/CanonicalGlossary.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - architecture and planning conversations involving overloaded identity terms + - comparing IAM, directory, and authorization vocabulary without forcing one product model + not_recommended_for: + - runtime identity resolution + - assuming draft canon entries are finalized standards + known_limitations: + - source-note backfill is incomplete + - mappings may remain candidate until evidence review completes +--- + +# Identity Vocabulary Canonicalization + +## Overview + +This capability makes identity vocabulary reusable for planning across adjacent +domains. It is intentionally research-heavy and informational, illustrating a +D4/A0/C2/R0 vector that contrasts with implementation-ready entries. + +## Current reuse mode + +Consumers read canon, terminology, and model artifacts in the identity-canon +repository. The value is planning reuse through shared vocabulary, not runtime +integration. + +## Relation to adjacent capabilities + +Feature-control evaluation depends on consistent subject and tenant concepts. +This capability supports that planning layer without providing runtime identity +services itself. \ No newline at end of file diff --git a/registry/capabilities/capability.registry.register.md b/registry/capabilities/capability.registry.register.md new file mode 100644 index 0000000..6893b75 --- /dev/null +++ b/registry/capabilities/capability.registry.register.md @@ -0,0 +1,134 @@ +--- +id: capability.registry.register +name: Capability Registration +summary: Register a new capability so it becomes visible for planning and implementation reuse. +owner: reuse-surface +status: draft +domain: helix_forge +tags: + - registry + - governance + - meta + +maturity: + discovery: + current: D3 + target: D5 + confidence: medium + rationale: > + Core use case UC-RS-001 is documented in specs/UseCaseCatalog.md and the + registry model is bounded in INTENT.md, but concrete promotion workflows + are not yet grounded in registry artifacts. + availability: + current: A0 + target: A3 + confidence: medium + rationale: > + Registration is currently manual through Markdown entries and the index. + A CLI validator/query tool would raise availability to A3. + +external_evidence: + completeness: + level: C1 + name: Fragmentary + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - capability IDs can be assigned in registry entries + - maturity vectors can be recorded at registration time + broken_expectations: + - no automated duplicate detection yet + - no promotion history tracking yet + out_of_scope_expectations: + - hosting registered capabilities + - enforcing implementation architecture + reliability: + level: R0 + confidence: low + basis: consumer_quality_signals + known_reliability_risks: + - registry consistency depends on manual index maintenance + +discovery: + intent: > + Make a capability candidate visible in the registry so humans and agents can + discover, assess, compare, and reuse it instead of rebuilding it in isolation. + includes: + - stable capability ID assignment + - initial discovery and availability classification + - explicit completeness and reliability placeholders + - evidence and relation references + excludes: + - implementing the registered capability + - certifying implementation quality + - operating runtime services for registered capabilities + assumptions: + - unregistered capabilities are invisible for registry-driven reuse + - low-maturity entries are acceptable when evidence gaps are explicit + use_cases: + - UC-RS-001 + research_memos: + - specs/UseCaseCatalog.md + - specs/ProductRequirementsDocument.md + +availability: + current_level: A0 + target_level: A3 + current_artifacts: + - templates/capability-entry.template.md + - registry/indexes/capabilities.yaml + target_artifacts: + - tools/validate-registry + - tools/query-registry + consumption_modes: + - informational + - markdown authoring + +relations: + depends_on: [] + supports: + - capability.feature-control.evaluate + - capability.identity.vocabulary-canonicalize + related_to: + - capability.registry.validate + +evidence: + documentation: + - INTENT.md + - specs/UseCaseCatalog.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - making a new capability visible at D0/A0/C0/R0 with minimal friction + - seeding planning discussions before implementation exists + not_recommended_for: + - treating registry presence as proof of implementation readiness + - skipping explicit evidence for maturity promotion + known_limitations: + - manual index updates are required after adding an entry + - duplicate detection is guidance-only in the MVP +--- + +# Capability Registration + +## Overview + +Registration is the entry point for reuse visibility. A capability that is not +registered cannot be discovered through the registry surface, even if code or +documentation exists elsewhere. + +## Current reuse mode + +Humans and agents add Markdown entries under `registry/capabilities/` and update +`registry/indexes/capabilities.yaml`. This is informational reuse (A0): read, +plan, and author entries. + +## Next promotion steps + +1. Attach concrete use cases and actors to reach D5. +2. Add a CLI validator to reach A3. +3. Record consumer expectations and broken expectations as external evidence. \ No newline at end of file diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml new file mode 100644 index 0000000..82aded8 --- /dev/null +++ b/registry/indexes/capabilities.yaml @@ -0,0 +1,38 @@ +# 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 / A0 / 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] + + - 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.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 + domain: helix_forge + status: draft + owner: identity-canon + path: registry/capabilities/capability.identity.vocabulary-canonicalize.md + tags: [identity, terminology, research] + consumption_modes: [informational] \ No newline at end of file diff --git a/schemas/capability.schema.yaml b/schemas/capability.schema.yaml new file mode 100644 index 0000000..418ce4f --- /dev/null +++ b/schemas/capability.schema.yaml @@ -0,0 +1,247 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://reuse-surface.local/schemas/capability.schema.yaml +title: Capability Registry Entry +description: > + JSON Schema for YAML front matter in Markdown capability entries under + registry/capabilities/. Aligns with specs/CapabilityMaturityStandard.md. +type: object +additionalProperties: false +required: + - id + - name + - summary + - owner + - status + - maturity + - external_evidence +properties: + id: + type: string + pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$' + description: Stable reverse-domain capability identifier. + name: + type: string + minLength: 1 + summary: + type: string + minLength: 1 + owner: + type: string + minLength: 1 + status: + type: string + enum: [draft, reviewed, approved, deprecated] + domain: + type: string + description: Optional domain or product scope for filtering. + tags: + type: array + items: + type: string + maturity: + type: object + additionalProperties: false + required: [discovery, availability] + properties: + discovery: + $ref: '#/$defs/internalMaturityDimension' + availability: + $ref: '#/$defs/internalMaturityDimension' + external_evidence: + type: object + additionalProperties: false + required: [completeness, reliability] + properties: + completeness: + $ref: '#/$defs/completenessEvidence' + reliability: + $ref: '#/$defs/reliabilityEvidence' + discovery: + type: object + additionalProperties: false + properties: + intent: + type: string + includes: + type: array + items: + type: string + excludes: + type: array + items: + type: string + assumptions: + type: array + items: + type: string + use_cases: + type: array + items: + type: string + research_memos: + type: array + items: + type: string + availability: + type: object + additionalProperties: false + properties: + current_level: + $ref: '#/$defs/availabilityLevel' + target_level: + $ref: '#/$defs/availabilityLevel' + current_artifacts: + type: array + items: + type: string + target_artifacts: + type: array + items: + type: string + consumption_modes: + type: array + items: + type: string + relations: + type: object + additionalProperties: false + properties: + depends_on: + $ref: '#/$defs/capabilityIdList' + supports: + $ref: '#/$defs/capabilityIdList' + used_by: + $ref: '#/$defs/capabilityIdList' + related_to: + $ref: '#/$defs/capabilityIdList' + specializes: + $ref: '#/$defs/capabilityIdList' + generalizes: + $ref: '#/$defs/capabilityIdList' + replaces: + $ref: '#/$defs/capabilityIdList' + wraps: + $ref: '#/$defs/capabilityIdList' + evidence: + type: object + additionalProperties: false + properties: + documentation: + type: array + items: + type: string + tests: + type: array + items: + type: string + consumer_feedback: + type: array + items: + type: string + bug_reports: + type: array + items: + type: string + incidents: + type: array + items: + type: string + consumer_guidance: + type: object + additionalProperties: false + properties: + recommended_for: + type: array + items: + type: string + not_recommended_for: + type: array + items: + type: string + known_limitations: + type: array + items: + type: string +$defs: + confidence: + type: string + enum: [low, medium, high] + discoveryLevel: + type: string + enum: [D0, D1, D2, D3, D4, D5, D6, D7] + availabilityLevel: + type: string + enum: [A0, A1, A2, A3, A4, A5, A6, A7] + completenessLevel: + type: string + enum: [C0, C1, C2, C3, C4, C5, C6] + reliabilityLevel: + type: string + enum: [R0, R1, R2, R3, R4, R5, R6] + capabilityIdList: + type: array + items: + type: string + pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$' + internalMaturityDimension: + type: object + additionalProperties: false + required: [current, target] + properties: + current: + oneOf: + - $ref: '#/$defs/discoveryLevel' + - $ref: '#/$defs/availabilityLevel' + target: + oneOf: + - $ref: '#/$defs/discoveryLevel' + - $ref: '#/$defs/availabilityLevel' + confidence: + $ref: '#/$defs/confidence' + rationale: + type: string + completenessEvidence: + type: object + additionalProperties: false + required: [level] + properties: + level: + $ref: '#/$defs/completenessLevel' + name: + type: string + confidence: + $ref: '#/$defs/confidence' + basis: + type: string + satisfied_expectations: + type: array + items: + type: string + broken_expectations: + type: array + items: + type: string + out_of_scope_expectations: + type: array + items: + type: string + reliabilityEvidence: + type: object + additionalProperties: false + required: [level] + properties: + level: + $ref: '#/$defs/reliabilityLevel' + name: + type: string + confidence: + $ref: '#/$defs/confidence' + basis: + type: string + evidence: + type: object + additionalProperties: true + known_reliability_risks: + type: array + items: + type: string \ No newline at end of file diff --git a/templates/capability-entry.template.md b/templates/capability-entry.template.md new file mode 100644 index 0000000..e55f2c6 --- /dev/null +++ b/templates/capability-entry.template.md @@ -0,0 +1,119 @@ +--- +# Copy this file to registry/capabilities/.md +# Replace placeholder values. Keep external_evidence separate from maturity. +id: capability.domain.example +name: Example Capability +summary: One sentence describing what this capability enables. +owner: team-or-person +status: draft +domain: helix_forge +tags: + - example + +maturity: + discovery: + current: D0 + target: D5 + confidence: low + rationale: > + Explain why the current discovery level is defensible and what evidence + is still missing for promotion. + availability: + current: A0 + target: A3 + confidence: low + rationale: > + Explain the current consumption mode and the natural target availability. + +external_evidence: + completeness: + level: C0 + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: [] + broken_expectations: [] + out_of_scope_expectations: [] + reliability: + level: R0 + confidence: low + basis: consumer_quality_signals + known_reliability_risks: [] + +discovery: + intent: > + What this capability is meant to make possible for planners and consumers. + includes: + - behavior that belongs inside the capability + excludes: + - behavior explicitly outside the capability + assumptions: + - assumptions shaping the capability boundary + use_cases: [] + research_memos: [] + +availability: + current_level: A0 + target_level: A3 + current_artifacts: [] + target_artifacts: [] + consumption_modes: + - informational + +relations: + depends_on: [] + supports: [] + related_to: [] + +evidence: + documentation: [] + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - describe suitable reuse scenarios + not_recommended_for: + - describe unsafe or weak reuse scenarios + known_limitations: + - list known gaps, risks, or missing evidence +--- + +# Example Capability + +## Overview + +Describe the capability in plain language for human readers. The YAML front +matter above is the machine-readable source of truth for maturity, evidence, +relations, and consumer guidance. + +## Assessment notes + +### Discovery + +Record why the selected discovery level is defensible. Link research memos, +use cases, and scope boundaries that support promotion. + +### Availability + +Record how consumers can access the capability today and what artifact would +raise availability to the target level. + +### Completeness + +Compare declared intent, current scope, and consumer expectations. Record broken +expectations explicitly rather than hiding them. + +### Reliability + +Record consumer-relevant quality evidence. Do not confuse reliability with +completeness or internal code quality. + +## Promotion checklist + +- [ ] ID follows `capability..` pattern +- [ ] Maturity enums match `specs/CapabilityMaturityStandard.md` +- [ ] `external_evidence` is populated separately from `maturity` +- [ ] Relations reference valid capability IDs +- [ ] Index entry added or updated in `registry/indexes/capabilities.yaml` \ No newline at end of file diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..0ea1cda --- /dev/null +++ b/tools/README.md @@ -0,0 +1,55 @@ +# Registry Tools + +Reference tooling for the capability registry. The MVP is document-first; this +directory documents validation and query workflows until executable tools land. + +## Current MVP workflows + +| Workflow | Location | Mode | +|---|---|---| +| Add capability | `templates/capability-entry.template.md` | manual | +| Discover capabilities | `registry/indexes/capabilities.yaml` | manual / agent | +| Validate entry shape | `registry/README.md` checklist | manual | +| Schema reference | `schemas/capability.schema.yaml` | manual | +| Maturity definitions | `specs/CapabilityMaturityStandard.md` | manual | + +## Manual validation procedure + +1. Open the capability entry Markdown file. +2. Compare YAML front matter against `schemas/capability.schema.yaml`. +3. Run the checklist in `registry/README.md`. +4. Confirm the index entry exists and the `vector` is current. +5. Confirm relation targets exist or are intentionally external. + +## Planned tools (out of MVP scope) + +Future CLI commands may include: + +```bash +# validate one entry or the whole registry +reuse-surface validate registry/capabilities/ + +# query by planning need, availability, or vector +reuse-surface query --discovery-min D4 --tag identity + +# export machine-readable registry bundle +reuse-surface export --format yaml +``` + +These are documented here as targets only. Do not assume they exist yet. + +## Agent query pattern + +Agents should start with the index, not individual entry files: + +1. Read `registry/indexes/capabilities.yaml`. +2. Filter by `vector`, `tags`, `consumption_modes`, or `summary`. +3. Open only the candidate entry paths. +4. Before creating a new capability, search for overlap using the duplicate + guidance in `registry/README.md`. + +## Related use cases + +- UC-RS-013 — Use registry metadata in agentic coding +- UC-RS-019 — Publish a machine-readable registry export +- UC-RS-023 — Validate registry entries against schema \ No newline at end of file diff --git a/workplans/REUSE-WP-0001-statehub-bootstrap.md b/workplans/REUSE-WP-0001-statehub-bootstrap.md index 242b492..e0e249b 100644 --- a/workplans/REUSE-WP-0001-statehub-bootstrap.md +++ b/workplans/REUSE-WP-0001-statehub-bootstrap.md @@ -4,11 +4,11 @@ type: workplan title: "Bootstrap State Hub integration" domain: helix_forge repo: reuse-surface -status: ready +status: finished owner: codex topic_slug: helix-forge created: "2026-06-14" -updated: "2026-06-14" +updated: "2026-06-15" state_hub_workstream_id: "293ef16d-c15b-41cc-9258-4a3a233f4bf2" --- @@ -20,7 +20,7 @@ Capability registry for planning and implementation reuse based on discovery and ```task id: REUSE-WP-0001-T01 -status: todo +status: done priority: high state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4" ``` @@ -28,11 +28,17 @@ state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4" Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. Replace generated placeholders with repo-specific facts where needed. +Completed by reviewing the generated integration files, preserving +`.custodian-brief.md` as generated output, and refining `SCOPE.md` to the +actual registry-first repository boundary. `INTENT.md` already contained +repo-specific intent and maturity model content; no placeholder replacement was +needed there. + ## Verify Local Developer Workflow ```task id: REUSE-WP-0001-T02 -status: todo +status: done priority: high state_hub_task_id: "0877cf67-6abe-48c3-b76c-df552620d678" ``` @@ -41,11 +47,16 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine those commands in the agent instructions so future coding sessions can verify changes confidently. +Completed by adding the local developer workflow to `AGENTS.md`. The repository +is documentation-only: no install, build, runtime service, package manifest, or +configured test runner exists. Current verification is `rg --files`, `git diff +--check`, and State Hub ADR-001 consistency sync after workplan changes. + ## Seed First Real Workplan ```task id: REUSE-WP-0001-T03 -status: todo +status: done priority: medium state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b" ``` @@ -56,3 +67,7 @@ next change. After workplan file updates, run from `~/state-hub`: ```bash make fix-consistency REPO=reuse-surface ``` + +Completed by `REUSE-WP-0002`, which seeds the MVP registry foundation: +schema, templates, sample capabilities, index, validation guidance, and agent +registry instructions. \ No newline at end of file diff --git a/workplans/REUSE-WP-0002-mvp-registry-foundation.md b/workplans/REUSE-WP-0002-mvp-registry-foundation.md new file mode 100644 index 0000000..19a61fd --- /dev/null +++ b/workplans/REUSE-WP-0002-mvp-registry-foundation.md @@ -0,0 +1,129 @@ +--- +id: REUSE-WP-0002 +type: workplan +title: "MVP registry foundation" +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: "32e0f249-65dd-4401-831c-736b229c5865" +--- + +# MVP registry foundation + +This workplan implements the first registry artifacts required by +`specs/ProductRequirementsDocument.md` section 15 (MVP Requirements) and section +16 (MVP Acceptance Criteria). The repository already has `INTENT.md`, the +product requirements, use case catalog, and capability maturity standard under +`specs/`. The remaining MVP work is to make the registry usable by humans and +agents. + +## Design decisions + +- **Canonical format:** Markdown capability entries with YAML front matter under + `registry/capabilities/`. The index at `registry/indexes/capabilities.yaml` + is the machine-readable discovery surface for agents. +- **Schema alignment:** Follow `INTENT.md` and `specs/CapabilityMaturityStandard.md` + section 10. Internal maturity uses `maturity.discovery` and + `maturity.availability`. Consumer evidence uses `external_evidence.completeness` + and `external_evidence.reliability` — not nested under `maturity`. +- **Sample capabilities:** Seed three helix_forge entries illustrating different + vectors: registry meta (`capability.registry.register`), implementation-ready + feature control (`capability.feature-control.evaluate`), and research-heavy + identity canon (`capability.identity.vocabulary-canonicalize`). +- **Validation:** Document manual validation rules in `registry/README.md` and + `tools/README.md` for MVP. Automated CLI validation is out of scope here. + +## Define Capability Schema + +```task +id: REUSE-WP-0002-T01 +status: done +priority: high +state_hub_task_id: "431edb19-2166-4715-bb3d-4428149aa2bc" +``` + +Create `schemas/capability.schema.yaml` as a JSON Schema draft (YAML syntax) +for registry entry front matter. Cover stable IDs, `maturity` (discovery and +availability only), `external_evidence`, discovery scope fields, availability +artifacts, relations, evidence references, and consumer guidance. Enum values +must match `specs/CapabilityMaturityStandard.md`. + +## Create Capability Entry Template + +```task +id: REUSE-WP-0002-T02 +status: done +priority: high +state_hub_task_id: "a4763385-954f-4141-9f16-a85e96704f46" +``` + +Create `templates/capability-entry.template.md` as the Markdown-first authoring +template. Include YAML front matter with required fields, commented guidance +for assessors, and placeholders for evidence, relations, and consumer guidance. +The template must be consistent with the schema from T01. + +## Seed Sample Registry Entries + +```task +id: REUSE-WP-0002-T03 +status: done +priority: high +state_hub_task_id: "96078fbb-f2cc-4d4f-ac7c-6a1744c33e0b" +``` + +Create three sample entries under `registry/capabilities/`: + +- `capability.registry.register.md` — D3/A0, meta registry capability +- `capability.feature-control.evaluate.md` — D5/A4, implementation-ready example +- `capability.identity.vocabulary-canonicalize.md` — D4/A0, research/planning example + +Each entry must conform to the schema and illustrate distinct maturity vectors. +Include relations between entries where appropriate. + +## Build Capability Index + +```task +id: REUSE-WP-0002-T04 +status: done +priority: medium +state_hub_task_id: "19e0d200-fe1f-4273-9f47-abdf4a67b517" +``` + +Create `registry/indexes/capabilities.yaml` as a manually maintained index. +Include IDs, names, summaries, compact maturity vectors, domain, and paths to +entry files. The index must list all three sample capabilities from T03. + +## Add Validation And Search Guidance + +```task +id: REUSE-WP-0002-T05 +status: done +priority: medium +state_hub_task_id: "bf0dd838-9c13-480e-93b9-47d4ae5edc82" +``` + +Create `registry/README.md` and `tools/README.md` documenting: + +- Required and recommended fields +- Manual validation checklist (schema enums, relation ID format, broken references) +- Search/filter guidance for UC-RS-004, UC-RS-005, UC-RS-006, and UC-RS-015 +- How to add a D0/A0/C0/R0 entry with minimal friction (MVP acceptance criteria) + +## Extend Agent Registry Instructions + +```task +id: REUSE-WP-0002-T06 +status: done +priority: medium +state_hub_task_id: "a78fc037-b432-4af3-a068-132690344bb2" +``` + +Add a **Capability Registry** section to `AGENTS.md` explaining how coding +agents should orient to the registry, query the index, add or promote entries +using the template, validate manually, and avoid duplicating existing +capabilities. Reference paths created in earlier tasks and map guidance to MVP +acceptance criteria in `specs/ProductRequirementsDocument.md` section 16. \ No newline at end of file