generated from coulomb/repo-seed
Bootstrap and first implementation
This commit is contained in:
130
AGENTS.md
130
AGENTS.md
@@ -101,6 +101,136 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 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.<domain>.<name>.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)
|
## Workplan Convention (ADR-001)
|
||||||
|
|
||||||
Work items originate as files in this repo — not in the hub. The hub is a
|
Work items originate as files in this repo — not in the hub. The hub is a
|
||||||
|
|||||||
41
SCOPE.md
41
SCOPE.md
@@ -1,32 +1,53 @@
|
|||||||
# SCOPE
|
# SCOPE
|
||||||
|
|
||||||
> This file was generated by `statehub register`. Refine it as the repository
|
|
||||||
> boundaries become clearer.
|
|
||||||
|
|
||||||
## One-liner
|
## One-liner
|
||||||
|
|
||||||
Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
||||||
|
|
||||||
## Core Idea
|
## 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
|
## In Scope
|
||||||
|
|
||||||
- Maintain the repository's primary implementation.
|
- Maintain the capability maturity model, standards, schemas, registry formats,
|
||||||
- Keep docs, tests, and operational metadata current.
|
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
|
## Out of Scope
|
||||||
|
|
||||||
- Own unrelated adjacent systems.
|
- Host or operate the registered capabilities themselves.
|
||||||
- Make irreversible operational decisions without human approval.
|
- 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
|
## 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
|
## Getting Oriented
|
||||||
|
|
||||||
- Start with: INTENT.md
|
- Start with: INTENT.md
|
||||||
|
- Product requirements: specs/ProductRequirementsDocument.md
|
||||||
|
- Use cases: specs/UseCaseCatalog.md
|
||||||
|
- Maturity standard: specs/CapabilityMaturityStandard.md
|
||||||
- Agent instructions: AGENTS.md
|
- Agent instructions: AGENTS.md
|
||||||
- Workplans: workplans/
|
- Workplans: workplans/
|
||||||
136
registry/README.md
Normal file
136
registry/README.md
Normal file
@@ -0,0 +1,136 @@
|
|||||||
|
# Capability Registry
|
||||||
|
|
||||||
|
Markdown-first registry for reusable capabilities in the helix_forge domain.
|
||||||
|
|
||||||
|
## Layout
|
||||||
|
|
||||||
|
```text
|
||||||
|
registry/
|
||||||
|
├── README.md
|
||||||
|
├── capabilities/
|
||||||
|
│ └── capability.<domain>.<name>.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.<domain>.<name>.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.
|
||||||
138
registry/capabilities/capability.feature-control.evaluate.md
Normal file
138
registry/capabilities/capability.feature-control.evaluate.md
Normal file
@@ -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.
|
||||||
@@ -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.
|
||||||
134
registry/capabilities/capability.registry.register.md
Normal file
134
registry/capabilities/capability.registry.register.md
Normal file
@@ -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.
|
||||||
38
registry/indexes/capabilities.yaml
Normal file
38
registry/indexes/capabilities.yaml
Normal file
@@ -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]
|
||||||
247
schemas/capability.schema.yaml
Normal file
247
schemas/capability.schema.yaml
Normal file
@@ -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
|
||||||
119
templates/capability-entry.template.md
Normal file
119
templates/capability-entry.template.md
Normal file
@@ -0,0 +1,119 @@
|
|||||||
|
---
|
||||||
|
# Copy this file to registry/capabilities/<id-with-dots-as-hyphens>.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.<domain>.<name>` 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`
|
||||||
55
tools/README.md
Normal file
55
tools/README.md
Normal file
@@ -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
|
||||||
@@ -4,11 +4,11 @@ type: workplan
|
|||||||
title: "Bootstrap State Hub integration"
|
title: "Bootstrap State Hub integration"
|
||||||
domain: helix_forge
|
domain: helix_forge
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: ready
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
topic_slug: helix-forge
|
topic_slug: helix-forge
|
||||||
created: "2026-06-14"
|
created: "2026-06-14"
|
||||||
updated: "2026-06-14"
|
updated: "2026-06-15"
|
||||||
state_hub_workstream_id: "293ef16d-c15b-41cc-9258-4a3a233f4bf2"
|
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
|
```task
|
||||||
id: REUSE-WP-0001-T01
|
id: REUSE-WP-0001-T01
|
||||||
status: todo
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4"
|
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`.
|
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
|
||||||
Replace generated placeholders with repo-specific facts where needed.
|
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
|
## Verify Local Developer Workflow
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: REUSE-WP-0001-T02
|
id: REUSE-WP-0001-T02
|
||||||
status: todo
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
state_hub_task_id: "0877cf67-6abe-48c3-b76c-df552620d678"
|
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
|
those commands in the agent instructions so future coding sessions can verify
|
||||||
changes confidently.
|
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
|
## Seed First Real Workplan
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: REUSE-WP-0001-T03
|
id: REUSE-WP-0001-T03
|
||||||
status: todo
|
status: done
|
||||||
priority: medium
|
priority: medium
|
||||||
state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b"
|
state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b"
|
||||||
```
|
```
|
||||||
@@ -56,3 +67,7 @@ next change. After workplan file updates, run from `~/state-hub`:
|
|||||||
```bash
|
```bash
|
||||||
make fix-consistency REPO=reuse-surface
|
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.
|
||||||
129
workplans/REUSE-WP-0002-mvp-registry-foundation.md
Normal file
129
workplans/REUSE-WP-0002-mvp-registry-foundation.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user