spec(SHARD-WP-0013): fold in confirmed reuse-surface coordinates + mechanism

reuse-surface = capability registry at /home/worsch/reuse-surface (helix_forge):
Markdown entries via templates/capability-entry.template.md, D/A/C/R maturity
vectors, reuse-surface CLI (validate/query/export/overlaps), hub at
reuse.coulomb.social. T1 now registers shard-wiki's capabilities as registry
entries; T3 contributes gaps back via REUSE-WP/agent message; T5 evaluates
reusing sibling feature-control for per-shard activation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-15 17:32:49 +02:00
parent d6d7cc555f
commit ec7a1ec946

View File

@@ -11,6 +11,7 @@ created: "2026-06-15"
updated: "2026-06-15"
depends_on:
- SHARD-WP-0002
state_hub_workstream_id: "04a25a53-2169-41d4-88c0-5035a06e72ef"
---
# SHARD-WP-0013 — Wiki-engine prep
@@ -46,10 +47,19 @@ architecture spec only. Implementation is a later workplan informed by `WikiEngi
- Architecture it must cohere with: `spec/CoreArchitectureBlueprint.md` (the engine is a
canonical-mode shard behind the §A contract), `spec/FederationRequirements.md`,
`spec/FederationArchitecture.md`.
- Reuse surface: the state-hub cross-domain capability registry (`list_capabilities`,
`register_capability`, `register_extension_point`, `request_capability`, gap analysis) and the
`capabilities` / `helix_forge` / `canon` domains. **T1 first confirms the exact target +
mechanism** (no "reuse-surface" domain/repo exists under that literal name).
- **Reuse surface (confirmed):** the **`reuse-surface`** repo (domain `helix_forge`, path
`/home/worsch/reuse-surface`, topic `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`, repo
`7007e599-6f2a-4fc6-b6c7-a86b6e9ccfaf`, workplan prefix `REUSE-WP-`). It is a **capability
registry**: Markdown capability entries in `registry/capabilities/` (from
`templates/capability-entry.template.md`) with a **D/A/C/R maturity model** (Discovery /
Availability / Completeness / Reliability vectors, e.g. `D0/A0/C0/R0`), an index
(`registry/indexes/capabilities.yaml`), a `reuse-surface` CLI (`query`, `validate`, `export`,
`overlaps`, `catalog`, `federation`, `hub`), and a hosted hub at `https://reuse.coulomb.social`.
Contributions to it follow **its** conventions (REUSE-WP, its own State-Hub-over-HTTP), since
it is a separate repo/domain.
- **Reuse candidate:** sibling repo **`feature-control`** (helix_forge) is directly relevant to
"activate only what you need per shard" — evaluate reusing it for per-shard feature activation
rather than inventing a bespoke mechanism (T5).
---
@@ -59,16 +69,20 @@ architecture spec only. Implementation is a later workplan informed by `WikiEngi
id: SHARD-WP-0013-T1
status: todo
priority: high
state_hub_task_id: "603cef8d-6b58-4d30-9283-201dab0f5fe9"
```
**Confirm** what the "reuse surface" is and how to contribute to it (the state-hub capability
registry vs. a specific `capabilities`/`helix_forge`/`canon`/`stack` repo) — resolve with the
user/owner if ambiguous. Then **register shard-wiki on it**: register its already-built and
planned capabilities (orchestration, shard adapter contract, page model, projection, overlay,
decision log, federation models) and **extension points** (the typed-extension surface the
engine will expose) via `register_capability` / `register_extension_point`, aligning vocabulary
with the capability taxonomy (`capabilities`) / HelixForge / `canon` profiles. Output: shard-wiki
visible on the reuse surface with a capability profile + declared extension points.
Target **confirmed** (Context): the `reuse-surface` capability registry at
`/home/worsch/reuse-surface`. **Register shard-wiki's capabilities as registry entries** there:
author a capability entry per shard-wiki capability (orchestration / shard adapter contract /
page model / projection / overlay / event-sourced decision log / federation models — and the
engine's planned typed-extension surface) using `templates/capability-entry.template.md`, set
honest **D/A/C/R maturity vectors** (built ones higher on Discovery/Availability; planned ones
at D-low), capture boundaries + relations + evidence (link the shard-wiki specs), update
`registry/indexes/capabilities.yaml`, and verify with **`reuse-surface validate`** +
**`overlaps`** (to catch reuse against existing entries). Follow reuse-surface's own conventions
(REUSE-WP / its State-Hub-over-HTTP) for any commits in that repo. Output: shard-wiki's
capabilities visible + assessable on the reuse surface.
## Systematize the UseCaseCatalog around a reuse-surface capability structure
@@ -76,6 +90,7 @@ visible on the reuse surface with a capability profile + declared extension poin
id: SHARD-WP-0013-T2
status: todo
priority: high
state_hub_task_id: "d83d0f96-7d95-405e-93cf-03314ab34636"
```
Re-structure (or add a structured layer over) `spec/UseCaseCatalog.md` so the 84 UCs map onto a
@@ -92,13 +107,17 @@ open-vs-governed, lossless-vs-lossy, live-vs-snapshot) and **how the framework m
id: SHARD-WP-0013-T3
status: todo
priority: medium
state_hub_task_id: "06b62406-39e7-4227-bcc6-f9cab1c28996"
```
Where T2 reveals features the engine needs that the reuse surface does **not** yet provide,
**contribute them back**: file `request_capability` / `register_extension_point` entries (or
`send_message` to the owning domain's agent) as suggestions, with the UC evidence. Produces a
tracked list of reuse-surface additions shard-wiki proposes (closing the loop the user asked
for: "if missing features, suggest to the reuse-surface repo via the state hub").
Where T2 reveals capabilities the engine needs that the reuse surface does **not** yet carry,
**contribute them back to `reuse-surface`**: propose new capability entries (or registry/schema
gaps) — via a message to the `reuse-surface` agent (`send_message`/its HTTP inbox) and/or a
`REUSE-WP` suggestion in that repo — each backed by the UC evidence from T2. Also note where
shard-wiki should *consume* an existing reuse-surface (or `feature-control`) capability rather
than build its own. Output: a tracked list of reuse-surface additions/consumptions shard-wiki
proposes (closing the loop: "if missing features, suggest to the reuse-surface repo via the
state hub").
## INTENT amendment + ratified decision (additive engine = reference shard backend)
@@ -106,6 +125,7 @@ for: "if missing features, suggest to the reuse-surface repo via the state hub")
id: SHARD-WP-0013-T4
status: todo
priority: high
state_hub_task_id: "1d0ef72b-2762-4086-9848-fde3b48c8454"
```
**Gate (Stability Note).** Amend `INTENT.md` to admit the engine *narrowly and additively*:
@@ -122,13 +142,16 @@ auth-in-core amendment.
id: SHARD-WP-0013-T5
status: todo
priority: high
state_hub_task_id: "4712bbfe-4ff3-4631-a9fb-e8857e1c0a2c"
```
Write **`spec/WikiEngineCoreArchitecture.md`**: the **small core + stringent typed-extension
framework**. Required content: (a) the minimal core (the irreducible engine kernel — page
lifecycle, storage via the §A contract, the extension/typing mechanism itself); (b) the
**typed-extension model** (how extensions declare types/contracts, compose, and are
**activated per shard** — only what you need); (c) how the **integrated featureset** from T2
**activated per shard** — only what you need; evaluate reusing the helix_forge
**`feature-control`** capability here rather than a bespoke activation mechanism); (c) how the
**integrated featureset** from T2
maps to core vs. extensions and how **conflicting requirements are mediated** into a consistent
whole; (d) how the engine sits as a **canonical-mode shard** behind the adapter contract
(consistency with `CoreArchitectureBlueprint`), so it federates like any other shard;
@@ -142,6 +165,7 @@ exotic case possible (mirror the CoreArchitectureBlueprint discipline).
id: SHARD-WP-0013-T6
status: todo
priority: medium
state_hub_task_id: "1c383414-2c8b-41c4-957d-8d1a9ed88143"
```
Update `SCOPE.md` (engine now in scope as the reference shard backend) and `spec/README.md`