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" updated: "2026-06-15"
depends_on: depends_on:
- SHARD-WP-0002 - SHARD-WP-0002
state_hub_workstream_id: "04a25a53-2169-41d4-88c0-5035a06e72ef"
--- ---
# SHARD-WP-0013 — Wiki-engine prep # 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 - Architecture it must cohere with: `spec/CoreArchitectureBlueprint.md` (the engine is a
canonical-mode shard behind the §A contract), `spec/FederationRequirements.md`, canonical-mode shard behind the §A contract), `spec/FederationRequirements.md`,
`spec/FederationArchitecture.md`. `spec/FederationArchitecture.md`.
- Reuse surface: the state-hub cross-domain capability registry (`list_capabilities`, - **Reuse surface (confirmed):** the **`reuse-surface`** repo (domain `helix_forge`, path
`register_capability`, `register_extension_point`, `request_capability`, gap analysis) and the `/home/worsch/reuse-surface`, topic `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`, repo
`capabilities` / `helix_forge` / `canon` domains. **T1 first confirms the exact target + `7007e599-6f2a-4fc6-b6c7-a86b6e9ccfaf`, workplan prefix `REUSE-WP-`). It is a **capability
mechanism** (no "reuse-surface" domain/repo exists under that literal name). 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 id: SHARD-WP-0013-T1
status: todo status: todo
priority: high 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 Target **confirmed** (Context): the `reuse-surface` capability registry at
registry vs. a specific `capabilities`/`helix_forge`/`canon`/`stack` repo) — resolve with the `/home/worsch/reuse-surface`. **Register shard-wiki's capabilities as registry entries** there:
user/owner if ambiguous. Then **register shard-wiki on it**: register its already-built and author a capability entry per shard-wiki capability (orchestration / shard adapter contract /
planned capabilities (orchestration, shard adapter contract, page model, projection, overlay, page model / projection / overlay / event-sourced decision log / federation models — and the
decision log, federation models) and **extension points** (the typed-extension surface the engine's planned typed-extension surface) using `templates/capability-entry.template.md`, set
engine will expose) via `register_capability` / `register_extension_point`, aligning vocabulary honest **D/A/C/R maturity vectors** (built ones higher on Discovery/Availability; planned ones
with the capability taxonomy (`capabilities`) / HelixForge / `canon` profiles. Output: shard-wiki at D-low), capture boundaries + relations + evidence (link the shard-wiki specs), update
visible on the reuse surface with a capability profile + declared extension points. `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 ## 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 id: SHARD-WP-0013-T2
status: todo status: todo
priority: high 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 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 id: SHARD-WP-0013-T3
status: todo status: todo
priority: medium 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, Where T2 reveals capabilities the engine needs that the reuse surface does **not** yet carry,
**contribute them back**: file `request_capability` / `register_extension_point` entries (or **contribute them back to `reuse-surface`**: propose new capability entries (or registry/schema
`send_message` to the owning domain's agent) as suggestions, with the UC evidence. Produces a gaps) — via a message to the `reuse-surface` agent (`send_message`/its HTTP inbox) and/or a
tracked list of reuse-surface additions shard-wiki proposes (closing the loop the user asked `REUSE-WP` suggestion in that repo — each backed by the UC evidence from T2. Also note where
for: "if missing features, suggest to the reuse-surface repo via the state hub"). 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) ## 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 id: SHARD-WP-0013-T4
status: todo status: todo
priority: high priority: high
state_hub_task_id: "1d0ef72b-2762-4086-9848-fde3b48c8454"
``` ```
**Gate (Stability Note).** Amend `INTENT.md` to admit the engine *narrowly and additively*: **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 id: SHARD-WP-0013-T5
status: todo status: todo
priority: high priority: high
state_hub_task_id: "4712bbfe-4ff3-4631-a9fb-e8857e1c0a2c"
``` ```
Write **`spec/WikiEngineCoreArchitecture.md`**: the **small core + stringent typed-extension Write **`spec/WikiEngineCoreArchitecture.md`**: the **small core + stringent typed-extension
framework**. Required content: (a) the minimal core (the irreducible engine kernel — page 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 lifecycle, storage via the §A contract, the extension/typing mechanism itself); (b) the
**typed-extension model** (how extensions declare types/contracts, compose, and are **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 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 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; (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 id: SHARD-WP-0013-T6
status: todo status: todo
priority: medium 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` Update `SCOPE.md` (engine now in scope as the reference shard backend) and `spec/README.md`