Add intent-scope gap analysis and REUSE-WP-0003 workplan

Document gaps between INTENT.md and SCOPE.md, refresh SCOPE with current
MVP capabilities, and seed the follow-up workplan for documentation
alignment, registry CLI tooling, and coverage growth.
This commit is contained in:
2026-06-15 01:09:53 +02:00
parent 3e022f4963
commit 80bccc4bbb
3 changed files with 553 additions and 9 deletions

View File

@@ -14,7 +14,7 @@ for reuse within this product boundary.
## In Scope
- Maintain the capability maturity model, standards, schemas, registry formats,
examples, indexes, validation guidance, and agent instructions.
sample entries, 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
@@ -32,22 +32,89 @@ for reuse within this product boundary.
- Own unrelated adjacent systems or make irreversible operational decisions
without human approval.
## What Is Possible Now
The MVP registry foundation is in place. Humans and agents can:
- **Discover capabilities** via `registry/indexes/capabilities.yaml`
- **Add a new capability** at D0/A0/C0/R0 using
`templates/capability-entry.template.md`
- **Promote capabilities** by updating front matter with evidence-backed
discovery, availability, completeness, and reliability levels
- **Compare candidates** using maturity vectors, scope, relations, and consumer
guidance in entry files
- **Record expectations** through `external_evidence.completeness` and
`external_evidence.reliability` fields
- **Validate entries manually** using the checklist in `registry/README.md`
against `schemas/capability.schema.yaml`
- **Avoid duplicates** by searching the index before creating new entries
These workflows satisfy the MVP acceptance criteria in
`specs/ProductRequirementsDocument.md` section 16 through manual, Git-friendly
authoring. There is no CLI, API, or automated validator yet.
## What Is Not Possible Yet
- Automated schema validation or registry export
- CLI query/filter commands
- Generated human-readable catalog site
- Capability graph visualization
- Promotion history tracking or review workflows in tooling
- Federation across repositories or organizations
See `tools/README.md` for planned tooling that remains out of scope for the
current MVP.
## Current State
- 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`.
- Status: active MVP registry (documentation-only, A0 availability).
- The repository has no package manifest, build system, runtime app, or
executable test suite. Registry consumption is informational: read, author,
compare, and plan.
- Three sample capabilities are registered in `registry/capabilities/`:
- `capability.registry.register` — D3 / A0 / C1 / R0
- `capability.feature-control.evaluate` — D5 / A4 / C3 / R3
- `capability.identity.vocabulary-canonicalize` — D4 / A0 / C2 / R0
- `specs/` holds the product requirements, use case catalog, and maturity
standard. `schemas/`, `templates/`, `registry/`, and `tools/` hold the
registry authoring and validation surfaces.
- Bootstrap work (`REUSE-WP-0001`) and MVP registry foundation
(`REUSE-WP-0002`) are finished. The next work should expand registry coverage,
tighten validation, or add CLI tooling through new workplans.
## Repository Layout
```text
reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── specs/
│ ├── ProductRequirementsDocument.md
│ ├── UseCaseCatalog.md
│ └── CapabilityMaturityStandard.md
├── schemas/
│ └── capability.schema.yaml
├── templates/
│ └── capability-entry.template.md
├── registry/
│ ├── README.md
│ ├── capabilities/
│ └── indexes/
│ └── capabilities.yaml
├── tools/
│ └── README.md
└── workplans/
```
## Getting Oriented
- Start with: INTENT.md
- Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
- Product requirements: specs/ProductRequirementsDocument.md
- Use cases: specs/UseCaseCatalog.md
- Maturity standard: specs/CapabilityMaturityStandard.md
- Registry index: registry/indexes/capabilities.yaml
- Registry guidance: registry/README.md
- Agent instructions: AGENTS.md
- Workplans: workplans/