diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9fa4f5a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,162 @@ +# reuse-surface — Agent Instructions + +## Repo Identity + +**Purpose:** Capability registry for planning and implementation reuse based on discovery and delivery maturity. + +**Domain:** helix_forge +**Repo slug:** reuse-surface +**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` +**Workplan prefix:** `REUSE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=reuse-surface&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=reuse-surface&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=reuse-surface + ``` + This syncs task status from files into the hub DB. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/REUSE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-REUSE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: REUSE-WP-NNNN +type: workplan +title: "..." +domain: helix_forge +repo: reuse-surface +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: REUSE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=reuse-surface` + (or send a message to the hub agent via `POST /messages/`) diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..d2f79d0 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,291 @@ +# INTENT.md — reuse-surface + +## Project Name + +`reuse-surface` + +## One-Line Intent + +`reuse-surface` provides a registry-centric capability reuse surface that makes capabilities visible, comparable, assessable, and reusable for planning, implementation, and operation. + +## Purpose + +The purpose of `reuse-surface` is to turn scattered capabilities into inspectable reuse assets. + +A capability that is not registered is effectively invisible for reuse. `reuse-surface` therefore treats registry membership as the boundary of relevance: once a capability is present in the registry, it can be discovered, assessed, compared, planned with, implemented against, improved, and eventually standardized. + +The project exists to answer four practical questions: + +1. **What capabilities do we have or intend to have?** +2. **How mature are they for planning reuse?** +3. **How available are they for implementation or operational reuse?** +4. **How well do consumers experience them in terms of completeness and reliability?** + +## Core Idea + +`reuse-surface` is not merely a catalog of features or services. It is a structured reuse layer for capabilities. + +A capability describes a bounded behavior or power that can be reused across products, repositories, systems, agents, workflows, or organizations. Features may expose capabilities. Services may deliver capabilities. Products may bundle capabilities. But the registry focuses on the reusable capability itself. + +The central assumption is: + +> A capability registry should not primarily describe what exists. It should describe what can be reused, at which confidence level, for which kind of work. + +## Scope + +`reuse-surface` shall provide the conceptual, structural, and eventually technical foundation for a capability registry. + +In scope: + +- capability registration +- capability identity and naming +- capability descriptions and boundaries +- discovery maturity assessment +- availability maturity assessment +- completeness assessment based on SCOPE vs INTENT and consumer expectations +- reliability assessment based on consumer-relevant quality signals +- relationships between capabilities +- evidence references for maturity claims +- registry formats usable by humans and agents +- planning support for prototype, MVP, enhancement, and platform decisions +- implementation support through discoverable consumption modes + +Out of scope for the initial intent: + +- judging internal code quality as capability maturity +- replacing feature maturity, service maturity, or operational maturity models +- enforcing one specific implementation architecture +- requiring all capabilities to become services or products +- treating unregistered capabilities as relevant for reuse analysis + +## Capability Maturity Dimensions + +`reuse-surface` uses four complementary dimensions. + +### Internal Registry Assessments + +These dimensions are assessed from the registry perspective. + +#### Discovery Maturity + +Discovery maturity measures how reusable the capability is for planning, orientation, comparison, roadmap design, and architectural reasoning. + +Canonical levels: + +- **D0 Named** — capability is visible in the registry. +- **D1 Described** — capability has meaning, intent, and context. +- **D2 Bounded** — scope, inclusions, exclusions, and neighboring capabilities are defined. +- **D3 Explored** — obvious relevant aspects have been investigated. +- **D4 Researched** — prior art, alternatives, products, standards, and tradeoffs have been deeply examined. +- **D5 Grounded** — concrete use cases, actors, scenarios, and prioritization criteria are documented. +- **D6 Exhaustive** — use-case and scope exploration has likely reached saturation. +- **D7 Generalized** — the capability has become a reusable planning primitive beyond one repo, product, or domain. + +#### Availability Maturity + +Availability maturity measures how directly the capability can be consumed for implementation or operation. + +Canonical levels: + +- **A0 Informational Only** — read and plan only. +- **A1 Experimental Prototype** — learn and experiment. +- **A2 Source Module / Library** — import and build with code. +- **A3 Command-Line Package** — automate via CLI. +- **A4 Service API / SDK** — integrate into applications. +- **A5 Containerized Service** — deploy and operate. +- **A6 Managed Platform Capability** — consume as an internal platform service. +- **A7 External Cloud Service Offering** — consume as a public or commercial cloud/API service. + +### External Consumer Evidence + +These dimensions are derived from consumer experience and evidence. + +#### Completeness + +Completeness measures how well current SCOPE satisfies declared INTENT and consumer expectations. + +Canonical levels: + +- **C0 Unknown** — no meaningful evidence. +- **C1 Fragmentary** — isolated parts of the expected capability are present. +- **C2 Partial** — some important expectations are satisfied, but major gaps remain. +- **C3 Functional Core** — the central expected use case works. +- **C4 Broadly Covered** — most common expectations are satisfied; gaps are known and bounded. +- **C5 Expectation Complete** — declared intent is substantially fulfilled for known expectations. +- **C6 Saturated** — further consumer discovery rarely reveals missing scope. + +#### Reliability + +Reliability measures how consistently the capability satisfies consumer-relevant quality expectations in real or realistic use. + +Canonical levels: + +- **R0 Unknown** — no meaningful evidence. +- **R1 Fragile** — frequently breaks, surprises, or disappoints consumers. +- **R2 Tolerable** — works in selected situations, but consumers must expect friction. +- **R3 Usable** — works reliably for normal use with known limitations. +- **R4 Dependable** — consumers can rely on it for important workflows. +- **R5 Trusted** — strong consumer confidence; failures are rare and well handled. +- **R6 Proven** — reliability is demonstrated across broad, repeated, and demanding use. + +## Capability Vector + +A registered capability may be summarized with a compact vector: + +```text +D5 / A4 / C3 / R3 +``` + +Meaning: + +- discovery maturity: grounded +- availability maturity: service API / SDK +- completeness: functional core +- reliability: usable + +The vector is descriptive, not a moral grade. Different capability types may have different target vectors. + +For example: + +- a research method may naturally target `D5 / A0 / C4 / R3` +- a CLI tool may naturally target `D5 / A3 / C5 / R5` +- an internal platform service may naturally target `D6 / A6 / C5 / R5` +- a commercial API offering may naturally target `D7 / A7 / C6 / R6` + +## Guiding Principles + +### Registry First + +Capabilities outside the registry are invisible for reuse analysis. The registry is the reuse surface. + +### Reuse Over Inventory + +The registry should optimize for capability reuse, not merely inventory completeness. + +### Planning and Implementation Are Different + +Planning reuse feeds primarily on discovery maturity. Implementation reuse feeds primarily on availability maturity. + +### Internal and External Evidence Must Stay Separate + +Discovery and availability are internal registry assessments. Completeness and reliability are external consumer-evidence dimensions. + +### Capability Maturity Is Not Feature Maturity + +Internal code structure, UI polish, local implementation elegance, and feature detail quality may matter, but they are not the same as capability maturity. They can be assessed separately when needed. + +### SCOPE vs INTENT Matters + +Completeness depends on the relationship between declared intent, current scope, and consumer expectations. Broken expectations are first-class evidence. + +### Consumer Experience Matters + +Reliability depends on consumer-relevant evidence such as bug reports, support tickets, incidents, failed integrations, ratings, adoption, retention, and qualitative feedback. + +### Target Maturity Should Be Explicit + +Not every capability needs to become a cloud service. Each capability should have a current vector and, where useful, a target vector. + +## Expected Registry Entry Shape + +A registry entry should eventually support a structure similar to: + +```yaml +id: capability.example +name: Example Capability +summary: Short capability summary. + +maturity: + discovery: + current: D2 + target: D5 + availability: + current: A1 + target: A4 + +external_evidence: + completeness: + current: C1 + confidence: low + reliability: + current: R0 + confidence: low + +discovery: + intent: What this capability is meant to make possible. + includes: [] + excludes: [] + assumptions: [] + use_cases: [] + research_memos: [] + +availability: + current_artifacts: [] + target_artifacts: [] + consumption_modes: [] + +relations: + depends_on: [] + supports: [] + related_to: [] + +evidence: + documentation: [] + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] +``` + +## Initial Repository Role + +The initial role of `reuse-surface` is to define and maintain the capability registry model, standards, schemas, examples, and reference tooling. + +Likely early repository contents: + +```text +reuse-surface/ +├── INTENT.md +├── README.md +├── standards/ +│ └── CapabilityMaturityStandard.md +├── registry/ +│ ├── capabilities.yaml +│ └── examples/ +├── schemas/ +│ └── capability.schema.json +├── docs/ +│ ├── CapabilityRegistryConcept.md +│ └── CapabilityAssessmentGuide.md +└── tools/ + └── README.md +``` + +## Success Criteria + +`reuse-surface` is successful when it helps humans and agents: + +- find reusable capabilities before rebuilding them +- compare capability maturity consistently +- distinguish conceptual readiness from delivery availability +- distinguish internal registry assessment from external consumer evidence +- plan prototype, MVP, enhancement, and platform work more effectively +- identify capability gaps, duplicates, overlaps, and standardization candidates +- track progress from named ideas to generalized reusable capabilities +- make capability reuse a normal part of product and architecture work + +## Non-Goals + +`reuse-surface` is not intended to become: + +- a generic feature tracker +- a project management replacement +- a service catalog only +- a CMDB only +- an implementation quality gate by itself +- a forced architecture pattern +- a claim that all reusable things must be services + +## Working Mantra + +> Make capabilities visible enough to plan with, available enough to build with, and evidenced enough to trust. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..dfe55ee --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,32 @@ +# 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. + +## In Scope + +- Maintain the repository's primary implementation. +- Keep docs, tests, and operational metadata current. + +## Out of Scope + +- Own unrelated adjacent systems. +- Make irreversible operational decisions without human approval. + +## Current State + +- Status: active; implementation and stability should be verified by the repo agent. + +## Getting Oriented + +- Start with: INTENT.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ diff --git a/specs/CapabilityMaturityStandard.md b/specs/CapabilityMaturityStandard.md new file mode 100755 index 0000000..a9bf99b --- /dev/null +++ b/specs/CapabilityMaturityStandard.md @@ -0,0 +1,1101 @@ +# Capability Maturity Standard + +Status: Draft 0.1 +Purpose: Define a registry-centric maturity model for reusable capabilities. +Scope: Capabilities that are present in a capability registry. Capabilities outside the registry are considered invisible for reuse analysis within this standard. + +--- + +## 1. Intent + +This standard defines how a capability registry assesses and communicates the maturity of registered capabilities. + +The standard is optimized for reuse. It distinguishes between: + +1. **Planning reuse** — using a capability to reason about product direction, roadmaps, architecture, MVP scope, enhancement planning, dependency graphs, and portfolio structure. +2. **Implementation reuse** — using a capability as something that can be consumed, called, installed, deployed, operated, integrated, or offered. + +The registry should not merely describe what exists. It should describe what can be reused, at which confidence level, and for which kind of work. + +--- + +## 2. Core Principle + +A registered capability has two internal maturity dimensions and two external evidence dimensions. + +```text +Capability Registry Assessment +├── Internal capability maturity +│ ├── Discovery maturity +│ └── Availability maturity +│ +└── External consumer evidence + ├── Completeness + └── Reliability +``` + +The four dimensions answer different questions: + +| Dimension | Type | Question | +|---|---|---| +| **Discovery** | Internal | How reusable is the capability for planning, orientation, comparison, roadmap design, and architectural reasoning? | +| **Availability** | Internal | How can implementation or operational consumers access and consume the capability? | +| **Completeness** | External | How well does current SCOPE satisfy declared INTENT and consumer expectations? | +| **Reliability** | External | How consistently does the capability satisfy consumer-relevant quality expectations? | + +This separation is important. A capability may be well understood but not implemented. It may be available as a service but poorly researched. It may cover only part of its intent but do that part very reliably. It may be broad in scope but frustrating to consume. + +--- + +## 3. Capability Registry Boundary + +This standard assumes that the capability registry is the boundary of relevance. + +Capabilities not present in the registry are out of scope for reuse assessment. They may exist in code, documentation, tacit practice, products, or agent behavior, but they are invisible for the purposes of registry-driven planning and implementation reuse. + +A capability may be registered at any maturity level. The registry should foster reuse of capabilities of all maturity levels, provided their maturity and evidence state are clearly represented. + +--- + +## 4. Capability Maturity Vector + +A capability maturity assessment should be represented as a vector. + +```text +Discovery / Availability / Completeness / Reliability +``` + +Example: + +```text +D5 / A4 / C3 / R2 +``` + +Meaning: + +- **D5 Grounded**: concrete use cases and scenarios are documented. +- **A4 Service API / SDK**: the capability is available for application-level integration. +- **C3 Functional Core**: the core expected scope is present, but variants and edge cases remain incomplete. +- **R2 Tolerable**: the capability works in selected situations, but consumers must expect friction. + +The vector is descriptive, not moral. Higher values do not always mean “better” for every capability. Some capabilities naturally target A0 or A3 rather than A7. Some capabilities are meant to remain informational standards or CLI tools. + +--- + +## 5. Discovery Maturity + +Discovery maturity measures how reusable a capability is for planning. + +It asks: + +```text +How well can this capability be reused for orientation, comparison, roadmap design, architecture, prioritization, and product planning? +``` + +Discovery maturity does not require implementation. + +### 5.1 Discovery Levels + +| Level | Name | Core meaning | Reuse value | +|---|---|---|---| +| **D0** | Named | Capability is visible in the registry. | Awareness and placeholder planning. | +| **D1** | Described | Capability has meaning, intent, and context. | Early clustering and orientation. | +| **D2** | Bounded | Scope, inclusions, exclusions, assumptions, and neighboring capabilities are defined. | Backlog, roadmap, and architecture planning. | +| **D3** | Explored | Obvious relevant aspects have been investigated. | Early planning with reduced naive uncertainty. | +| **D4** | Researched | Prior art, alternatives, products, standards, patterns, and tradeoffs have been deeply examined. | Informed option selection and investment decisions. | +| **D5** | Grounded | Concrete use cases, actors, scenarios, variants, and prioritization criteria are documented. | MVP, roadmap, enhancement, and implementation sequencing. | +| **D6** | Exhaustive | Scope and use-case exploration have likely reached saturation. | High-confidence standardization and major investment planning. | +| **D7** | Generalized | Capability has become a reusable planning primitive beyond one repo, product, or domain. | Canonical planning and cross-context reuse. | + +Short ladder: + +```text +Named → Described → Bounded → Explored → Researched → Grounded → Exhaustive → Generalized +``` + +### 5.2 D0 — Named + +The capability is registered and named. + +Minimum evidence: + +```yaml +id: capability.example +name: Example Capability +summary: One sentence or rough phrase +``` + +Reuse guidance: + +- Useful as a visible placeholder. +- Not yet suitable for serious planning. +- Interpretations may differ strongly between consumers. + +### 5.3 D1 — Described + +The capability has a meaningful description, rough intent, and basic context. + +Expected evidence: + +```yaml +discovery: + level: D1 + has: + - summary + - intent + - basic actors + - basic context +``` + +Reuse guidance: + +- Useful for early planning conversations. +- Useful for clustering related work. +- Boundaries may still be fuzzy. + +### 5.4 D2 — Bounded + +The capability has defined scope. + +Expected evidence: + +```yaml +includes: + - behavior that belongs inside the capability +excludes: + - behavior that is explicitly outside the capability +assumptions: + - assumptions shaping the capability boundary +related_capabilities: + - capability.neighboring.example +``` + +Reuse guidance: + +- Suitable for backlog and roadmap structure. +- Suitable for dependency mapping. +- May still lack research and use-case depth. + +### 5.5 D3 — Explored + +Obvious relevant aspects have been investigated. + +This level does not claim systematic breadth or depth. It only claims that directly visible questions, risks, assumptions, and comparable examples have been examined enough to reduce naive uncertainty. + +Expected evidence: + +```yaml +exploration: + questions_checked: + - What is the most obvious implementation direction? + - Which adjacent capabilities are clearly involved? + - What are the most visible risks? + - Which known tools, products, or examples immediately come to mind? + - What assumptions look dangerous? + notes: + - exploration/initial-notes.md + - exploration/obvious-risks.md + - exploration/first-tool-scan.md +``` + +Reuse guidance: + +- Suitable for early shaping and planning discussion. +- Not yet strong enough for major architectural investment decisions. +- Helps avoid obvious blind spots. + +### 5.6 D4 — Researched + +The capability space has been systematically researched. + +Expected evidence: + +```yaml +research: + memos: + - research/prior-art.md + - research/standards.md + - research/product-comparison.md + - research/architecture-options.md + alternatives: + - build + - buy + - adapt open source + - integrate managed service + tradeoffs: + - option A vs option B + - local vs remote + - embedded vs service-based +``` + +Reuse guidance: + +- Suitable for architectural decisions. +- Suitable for MVP and investment choices. +- Reduces rediscovery by documenting prior art and alternatives. + +### 5.7 D5 — Grounded + +The capability is grounded in concrete use cases, actors, scenarios, variants, and prioritization criteria. + +Expected evidence: + +```yaml +use_cases: + - id: ucc.example.primary + actor: primary consumer + summary: Main scenario supported by the capability. + frequency: high + criticality: medium + mvp_relevance: high +selection_dimensions: + user_value: high + implementation_risk: medium + reuse_potential: high + dependency_pressure: medium +``` + +Reuse guidance: + +- Suitable for roadmap design. +- Suitable for MVP selection. +- Suitable for enhancement planning. +- Suitable for implementation sequencing. + +### 5.8 D6 — Exhaustive + +Scope and use-case exploration have likely reached saturation. + +This does not mean perfect knowledge. It means that further research is unlikely to reveal materially new use-case categories. New findings are expected to become refinements, edge cases, or domain-specific variants rather than fundamentally new categories. + +Expected evidence: + +```yaml +exhaustiveness: + use_case_inventory: + status: saturated + coverage_notes: Known use cases cover the major actor groups, contexts, lifecycle stages, and integration modes. + explored_dimensions: + - actor types + - consumer types + - lifecycle stages + - operational contexts + - tenant/vendor/customer variants + - failure modes + - integration modes + - governance scenarios + saturation_indicators: + - repeated research produces already-known categories + - new findings map to existing use-case families + - stakeholder reviews do not reveal major missing categories + - competitor/product analysis no longer adds new use-case classes + remaining_uncertainty: + - niche domain-specific variants may still exist + - future technology shifts may create new cases +``` + +Reuse guidance: + +- Suitable for standardization. +- Suitable for major investment decisions. +- Suitable as input to canonization. + +### 5.9 D7 — Generalized + +The capability has been abstracted into a reusable planning primitive beyond one repo, product, domain, or implementation. + +Expected evidence: + +```yaml +generalization: + applies_to: + - repo-level planning + - product-level planning + - platform-level planning + - ecosystem-level planning + variants: + - variant A + - variant B + anti_patterns: + - common misuse or confused boundary + canonical_dependencies: + - capability.dependency.example +``` + +Reuse guidance: + +- Suitable as a canonical planning primitive. +- Suitable for cross-repo and cross-product architecture. +- Suitable for capability canon inclusion. + +--- + +## 6. Availability Maturity + +Availability maturity measures how the capability is available to implementation or operational consumers. + +It asks: + +```text +How directly can this capability be consumed for implementation or operation? +``` + +Availability is not primarily a measure of internal implementation quality. It describes consumption mode. + +### 6.1 Availability Levels + +| Level | Name | Consumer reuse mode | +|---|---|---| +| **A0** | Informational Only | Read, plan, and reason. | +| **A1** | Experimental Prototype | Learn, experiment, and inspect feasibility. | +| **A2** | Source Module / Library | Import, vendor, call, or build with code. | +| **A3** | Command-Line Package | Install and automate through CLI or process invocation. | +| **A4** | Service API / SDK | Integrate through API or language SDK. | +| **A5** | Containerized Service | Deploy and operate as a service. | +| **A6** | Managed Platform Capability | Consume as an internally managed platform service. | +| **A7** | External Cloud Service Offering | Consume as a public, commercial, or ecosystem-facing cloud service. | + +Short ladder: + +```text +Documented → Tried → Coded → Packaged → Integrated → Deployed → Managed → Offered +``` + +### 6.2 A0 — Informational Only + +The capability is registered and may be documented, but there is no consumable implementation. + +Consumer can: + +- Read documentation. +- Reuse concepts. +- Plan implementation. + +Consumer cannot: + +- Call it. +- Install it. +- Deploy it. +- Depend on runtime behavior. + +### 6.3 A1 — Experimental Prototype + +There is a prototype, spike, notebook, script, demo, or proof of concept. + +Consumer can: + +- Inspect approach. +- Run with effort. +- Copy ideas. +- Use for feasibility checks. + +Consumer should not: + +- Assume stable behavior. +- Depend on it as an implementation dependency. + +### 6.4 A2 — Source Module / Library + +The capability exists as production-oriented source code or a library module inside a repo. + +Consumer can: + +- Import it. +- Call functions, classes, or modules. +- Write tests against it. +- Reuse it at code level. + +Typical artifacts: + +- Source module. +- Internal library. +- Package dependency. + +### 6.5 A3 — Command-Line Package + +The capability is available as an installable CLI command or binary. + +Consumer can: + +- Install it. +- Call it from shell scripts. +- Use it in CI/CD. +- Compose it with other command-line tools. +- Expose it to agentic workflows. + +Typical artifacts: + +- CLI package. +- Binary release. +- Package-manager installation. + +### 6.6 A4 — Service API / SDK + +The capability is available through a stable service API and/or SDK. + +Consumer can: + +- Integrate it into applications. +- Call it remotely or locally. +- Use language-level SDK abstractions. +- Embed it into service workflows. + +Typical artifacts: + +- REST API. +- GraphQL API. +- gRPC API. +- Language SDK. +- OpenAPI specification. + +### 6.7 A5 — Containerized Service + +The capability is available as a deployable service container. + +Consumer can: + +- Deploy it. +- Run it as infrastructure. +- Integrate it into platform environments. +- Operate it in controlled infrastructure. + +Typical artifacts: + +- Container image. +- Docker Compose service. +- Helm chart. +- Kubernetes manifests. + +### 6.8 A6 — Managed Platform Capability + +The capability is available as a managed service inside a platform environment. + +Consumer can: + +- Request access. +- Configure usage. +- Consume platform APIs. +- Rely on platform operation and support. + +Typical artifacts: + +- Internal platform service. +- Shared tenant-aware service. +- Platform API. +- Platform documentation. +- Operational ownership model. + +### 6.9 A7 — External Cloud Service Offering + +The capability is available as an externally consumable cloud, SaaS, API, or marketplace offering. + +Consumer can: + +- Sign up. +- Subscribe. +- Integrate externally. +- Consume under explicit service terms. + +Typical artifacts: + +- SaaS product. +- Public API. +- Managed cloud service. +- Marketplace offering. +- External documentation. +- Support and billing model. + +### 6.10 Target Availability + +Availability levels are not strictly better in all cases. They represent increasing external availability, not universal desirability. + +Each capability should declare both current and target availability where useful. + +```yaml +availability: + current: A2 + target: A5 + reason: Needed as a deployable service for multi-tenant platform integration. +``` + +Examples of natural targets: + +| Capability type | Natural target | +|---|---| +| Architectural pattern | A0 | +| Research method | A0 or A1 | +| Markdown validation | A3 | +| Agent helper tool | A3 or A4 | +| Identity lookup | A4 | +| Feature control | A4, A5, or A6 | +| Tenant management | A6 | +| Public document conversion API | A7 | + +--- + +## 7. Completeness + +Completeness is an external consumer evidence dimension. + +It measures: + +```text +How well does current SCOPE satisfy declared INTENT and consumer expectations? +``` + +Completeness is not about availability or reliability. It is about whether consumers get the breadth and depth of behavior they reasonably expect from the capability’s stated intent. + +### 7.1 Completeness Levels + +| Level | Name | Meaning | +|---|---|---| +| **C0** | Unknown | No meaningful evidence about scope versus intent. | +| **C1** | Fragmentary | Only isolated parts of the expected capability are present. | +| **C2** | Partial | Some important expectations are satisfied, but major gaps remain. | +| **C3** | Functional Core | The central expected use case works, but variants and edge cases are incomplete. | +| **C4** | Broadly Covered | Most common consumer expectations are satisfied; gaps are known and bounded. | +| **C5** | Expectation Complete | Declared intent is substantially fulfilled for known consumer expectations. | +| **C6** | Saturated | Further consumer discovery rarely reveals missing scope; new requests are mostly extensions, optimizations, or domain-specific variants. | + +### 7.2 C0 — Unknown + +There is not enough evidence to assess completeness. + +Evidence state: + +```yaml +completeness: + level: C0 + evidence: + - no consumer feedback + - no explicit intent/scope comparison + - no expectation tracking +``` + +### 7.3 C1 — Fragmentary + +The capability satisfies a few isolated expectations, but does not yet cover the recognizable core of its declared intent. + +Reuse implication: + +- Useful fragments exist. +- Consumers will quickly hit missing scope. + +### 7.4 C2 — Partial + +Some important expectations are satisfied, but major expected areas are missing. + +Reuse implication: + +- Useful in selected situations. +- Not safe to present as generally complete. + +### 7.5 C3 — Functional Core + +The main expected use case works end-to-end. + +Variants, advanced cases, edge cases, administrative convenience, and uncommon consumer scenarios may still be incomplete. + +Reuse implication: + +- Often the minimum level for serious early adoption. +- Consumers can use the core, but must expect missing surrounding scope. + +### 7.6 C4 — Broadly Covered + +Most common consumer expectations are satisfied. + +Remaining gaps are known, documented, and do not break the central promise for ordinary use. + +Reuse implication: + +- Most consumers can use this without feeling misled by the declared intent. + +### 7.7 C5 — Expectation Complete + +The capability substantially fulfills its declared intent for known consumer expectations. + +Broken expectations are rare, minor, or clearly outside the declared scope. + +Reuse implication: + +- Promise and delivered scope are well aligned. + +### 7.8 C6 — Saturated + +The capability has reached expectation saturation. + +Further consumer feedback rarely reveals missing scope. New requests mostly represent: + +- Domain-specific variants. +- Performance improvements. +- UX refinements. +- Integration adapters. +- Commercial packaging. +- Future strategic extensions. + +Reuse implication: + +- The capability is complete not only against current expectations, but also stable enough that its scope model is unlikely to be surprised. + +### 7.9 Completeness Evidence + +Completeness should be assessed from evidence such as: + +```yaml +completeness_evidence: + declared_intent: + - what the capability claims to enable + current_scope: + - what the capability actually covers + satisfied_expectations: + - expectations confirmed as met by consumers + broken_expectations: + - expectations consumers had that were not met + out_of_scope_expectations: + - expectations rejected as not belonging to this capability + requested_extensions: + - useful but non-core additions + repeated_surprises: + - expectations that keep appearing unexpectedly +``` + +--- + +## 8. Reliability + +Reliability is an external consumer evidence dimension. + +It measures: + +```text +How consistently does the capability satisfy consumer-relevant quality expectations in real or realistic use? +``` + +Reliability is independent of completeness. A capability may be incomplete but reliable within its current scope. + +### 8.1 Reliability Levels + +| Level | Name | Meaning | +|---|---|---| +| **R0** | Unknown | No meaningful evidence about consumer-relevant quality. | +| **R1** | Fragile | Frequently breaks, surprises, or disappoints consumers. | +| **R2** | Tolerable | Works in some situations, but consumers must expect friction. | +| **R3** | Usable | Works reliably for normal use, with known limitations. | +| **R4** | Dependable | Consumers can rely on it for important workflows. | +| **R5** | Trusted | Strong consumer confidence; failures are rare and well-handled. | +| **R6** | Proven | Reliability is demonstrated across broad, repeated, and demanding use. | + +### 8.2 R0 — Unknown + +There is not enough evidence to assess reliability. + +Evidence state: + +```yaml +reliability: + level: R0 + evidence: + - no bug reports + - no consumer feedback + - no operational history + - no realistic test usage +``` + +### 8.3 R1 — Fragile + +The capability frequently fails, behaves unpredictably, or produces consumer disappointment. + +Failures may include: + +- Crashes. +- Confusing errors. +- Broken examples. +- Inconsistent behavior. +- Repeated support issues. +- Poor documentation. + +Reuse implication: + +- Suitable only for tolerant early adopters or controlled experiments. + +### 8.4 R2 — Tolerable + +The capability works in selected situations, but consumers need caution. + +There may be known defects, missing diagnostics, unstable edge cases, or poor performance under some expected conditions. + +Reuse implication: + +- Consumers can use it, but should expect friction and workarounds. + +### 8.5 R3 — Usable + +The capability works reliably for normal use within its declared scope. + +Known limitations are documented. Failures are understandable enough that consumers can usually recover. + +Reuse implication: + +- Acceptable for normal internal usage. +- Not yet a deeply trusted dependency for critical workflows. + +### 8.6 R4 — Dependable + +The capability is reliable enough for important workflows. + +Consumer-relevant quality dimensions are monitored or regularly reviewed. Bugs occur, but they are not systemic, and fixes are handled predictably. + +Reuse implication: + +- Consumers can build serious workflows on top of it. + +### 8.7 R5 — Trusted + +The capability has earned strong consumer confidence. + +Failures are rare, visible, explainable, and handled through mature support, documentation, observability, and change management. + +Reuse implication: + +- Consumers trust this as a stable building block. + +### 8.8 R6 — Proven + +The capability is proven across broad, repeated, and demanding use. + +Evidence may include production history, diverse consumers, incident records, bug trends, adoption retention, compatibility history, and sustained consumer satisfaction. + +Reuse implication: + +- Suitable as a proven platform or canonical dependency. + +### 8.9 Reliability Evidence + +Reliability should be assessed from consumer-relevant evidence such as: + +```yaml +reliability_evidence: + bug_reports: + - volume + - severity + - recurrence + - time_to_resolution + support_feedback: + - support tickets + - documentation complaints + - repeated confusion + operational_evidence: + - incidents + - error rates + - latency + - uptime + - retry/failure patterns + consumer_feedback: + - ratings + - star ratings + - reviews + - adoption retention + - churn + compatibility_evidence: + - breaking changes + - migration pain + - version adoption + integration_evidence: + - failed integrations + - successful integrations + - consumer workarounds +``` + +--- + +## 9. Relationship Between Dimensions + +The four dimensions are independent. + +Examples: + +| Vector | Interpretation | +|---|---| +| **D6 / A0 / C0 / R0** | Scope is deeply understood, but there is no implementation and no consumer evidence. | +| **D2 / A3 / C3 / R3** | Bounded capability, available as CLI, with functional core and normal usability. | +| **D1 / A5 / C2 / R2** | Deployable service exists, but conceptual framing is weak and consumer experience is limited. | +| **D5 / A4 / C4 / R4** | Use-case grounded capability, available through API/SDK, broadly covered and dependable. | +| **D7 / A6 / C5 / R5** | Generalized planning asset, managed internally, expectation-complete and trusted. | +| **D7 / A7 / C6 / R6** | Generalized capability, externally offered, saturated in scope and proven in demanding use. | + +Important distinctions: + +| Pair | Distinction | +|---|---| +| **Discovery vs Availability** | Understanding a capability is different from consuming it. | +| **Discovery D6 vs Completeness C6** | D6 means the use-case space is probably saturated; C6 means the delivered/current scope satisfies consumer expectations so fully that new feedback rarely reveals missing scope. | +| **Completeness vs Reliability** | Completeness asks whether enough scope is covered; reliability asks whether the covered scope behaves well. | +| **Availability vs Reliability** | A capability can be widely available but unreliable, or minimally available but highly reliable within its context. | + +--- + +## 10. Registry Entry Shape + +A capability registry entry should include maturity and evidence fields in a structure similar to the following. + +```yaml +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. + +maturity: + discovery: + current: D5 + target: D7 + availability: + current: A4 + target: A6 + +external_evidence: + completeness: + level: C3 + name: Functional Core + score: 0.58 + 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 + score: 0.64 + confidence: medium + basis: consumer_quality_signals + evidence: + bug_reports: + severity_trend: stable + recurring_bugs: moderate + time_to_resolution: acceptable + support_feedback: + repeated_confusion: moderate + documentation_complaints: moderate + operational_evidence: + incidents: rare + error_rate: within_expected_bounds + consumer_feedback: + average_rating: 3.8 + adoption_retention: moderate + 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 + research_memos: + - research/openfeature.md + - research/unleash.md + - research/flipt.md + - research/launchdarkly.md + use_cases: + - ucc.feature-control.tenant-toggle + - ucc.feature-control.agent-disable + - ucc.feature-control.domain-rollout + +availability: + current_level: A4 + target_level: A6 + current_artifacts: + - packages/feature-control-sdk + - services/feature-control-api + target_artifacts: + - charts/feature-control + - platform/feature-control-service + consumption_modes: + - SDK + - service API + - managed platform service + +relations: + depends_on: + - capability.identity.subject-resolution + - capability.tenant.context-resolution + - capability.policy.rule-evaluation + supports: + - capability.feature-control.rollout + - capability.feature-control.visibility +``` + +--- + +## 11. Assessment Guidance + +### 11.1 Do Not Collapse Dimensions + +Assessors must not treat one dimension as a proxy for another. + +Examples: + +- A service being containerized does not imply it is reliable. +- A capability being researched does not imply it is complete. +- A capability being expectation-complete does not imply it is generalized. +- A capability being generalized does not imply it is available as code. + +### 11.2 Use Evidence, Not Optimism + +All levels above the lowest levels should reference evidence. + +Evidence can include: + +- Registry metadata. +- INTENT and SCOPE documents. +- Research memos. +- Use case catalogs. +- Prior art comparisons. +- Architecture decision records. +- Tests and examples. +- API or SDK documentation. +- Package releases. +- Deployment manifests. +- Consumer feedback. +- Support tickets. +- Bug reports. +- Incident records. +- Ratings and reviews. +- Adoption and retention data. + +### 11.3 Track Current and Target State + +Capabilities should generally track current and target state. + +```yaml +maturity: + discovery: + current: D3 + target: D5 + availability: + current: A1 + target: A4 +external_evidence: + completeness: + current: C1 + target: C3 + reliability: + current: R0 + target: R3 +``` + +Target state should reflect the natural purpose of the capability, not an automatic desire to reach the maximum level in every dimension. + +### 11.4 Explain Confidence + +Each assessment should optionally include confidence. + +```yaml +confidence: low | medium | high +``` + +Low confidence is acceptable if the registry makes it visible. + +--- + +## 12. Summary Tables + +### 12.1 Discovery + +| Level | Name | +|---|---| +| D0 | Named | +| D1 | Described | +| D2 | Bounded | +| D3 | Explored | +| D4 | Researched | +| D5 | Grounded | +| D6 | Exhaustive | +| D7 | Generalized | + +### 12.2 Availability + +| Level | Name | +|---|---| +| A0 | Informational Only | +| A1 | Experimental Prototype | +| A2 | Source Module / Library | +| A3 | Command-Line Package | +| A4 | Service API / SDK | +| A5 | Containerized Service | +| A6 | Managed Platform Capability | +| A7 | External Cloud Service Offering | + +### 12.3 Completeness + +| Level | Name | +|---|---| +| C0 | Unknown | +| C1 | Fragmentary | +| C2 | Partial | +| C3 | Functional Core | +| C4 | Broadly Covered | +| C5 | Expectation Complete | +| C6 | Saturated | + +### 12.4 Reliability + +| Level | Name | +|---|---| +| R0 | Unknown | +| R1 | Fragile | +| R2 | Tolerable | +| R3 | Usable | +| R4 | Dependable | +| R5 | Trusted | +| R6 | Proven | + +--- + +## 13. Canonical Short Form + +The canonical short form for communicating capability maturity is: + +```text +D / A / C / R +``` + +Example: + +```text +D5 / A4 / C3 / R3 +``` + +A human-readable rendering may add names: + +```text +D5 Grounded / A4 Service API / C3 Functional Core / R3 Usable +``` + +--- + +## 14. Future Extensions + +This standard deliberately excludes internal implementation quality, because internal structure may belong to feature maturity, code maturity, service maturity, or operational maturity. + +Possible future companion standards: + +- Feature Maturity Standard. +- Service Operations Maturity Standard. +- Capability Registry Schema Standard. +- Use Case Scoring Standard. +- Capability Evidence Standard. +- Capability Graph Standard. diff --git a/workplans/REUSE-WP-0001-statehub-bootstrap.md b/workplans/REUSE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..242b492 --- /dev/null +++ b/workplans/REUSE-WP-0001-statehub-bootstrap.md @@ -0,0 +1,58 @@ +--- +id: REUSE-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: helix_forge +repo: reuse-surface +status: ready +owner: codex +topic_slug: helix-forge +created: "2026-06-14" +updated: "2026-06-14" +state_hub_workstream_id: "293ef16d-c15b-41cc-9258-4a3a233f4bf2" +--- + +# Bootstrap State Hub integration + +Capability registry for planning and implementation reuse based on discovery and delivery maturity. + +## Review Generated Integration Files + +```task +id: REUSE-WP-0001-T01 +status: todo +priority: high +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. + +## Verify Local Developer Workflow + +```task +id: REUSE-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "0877cf67-6abe-48c3-b76c-df552620d678" +``` + +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. + +## Seed First Real Workplan + +```task +id: REUSE-WP-0001-T03 +status: todo +priority: medium +state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run from `~/state-hub`: + +```bash +make fix-consistency REPO=reuse-surface +```