shard-wiki/workplans/SHARD-WP-0013-wiki-engine-prep.md

---
id: SHARD-WP-0013
type: workplan
title: "wiki-engine prep — reuse-surface registration, UC-catalog systematization, WikiEngineCoreArchitecture"
domain: whynot
repo: shard-wiki
status: done
owner: tegwick
topic_slug: whynot
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

## Goal

Prepare for shard-wiki to **also provide a native wiki-engine** — a best-in-class, elegant
architecture: a **small core** realizing a **stringent typed-extension framework** that
addresses *all* collected use cases, **mediates conflicting requirements** into a consistent
whole, is modeled as an **integrated featureset**, yet lets a shard **activate only what it
needs**. This workplan does the *preparation*, not the engine build: (1) register shard-wiki on
the **reuse surface**, (2) **systematize the UseCaseCatalog** around a reuse-surface-aligned
capability structure, surfacing missing-feature suggestions back to the reuse surface, and
(3) author **`spec/WikiEngineCoreArchitecture.md`**.

### Framing (the architectural reconciliation — read first)

A wiki-*engine* touches an INTENT boundary ("orchestrator, not engine"; the Stability Note
flags exactly this). The reconciliation that keeps INTENT intact: **the engine is shard-wiki's
reference first-party shard backend — a *canonical-mode shard* it implements natively against
its own adapter contract (TSD §A).** It is *one shard type among many*, not a mandate and not a
replacement for other engines (INTENT non-goal "replace all wiki engines" stays honoured;
union-without-erasure stays). shard-wiki keeps orchestrating; it simply now ships the most
capable shard it can attach — itself. This makes the engine **additive**, and reduces the
INTENT change to a narrow amendment (T4), not a redefinition.

**Non-goal (this workplan):** implementing the engine, its rendering/UI, or extensions. Prep +
architecture spec only. Implementation is a later workplan informed by `WikiEngineCoreArchitecture.md`.

## Context

- Demand: `spec/UseCaseCatalog.md` (84 UCs across 7 themes) — the featureset the engine must cover.
- 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 (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).

---

## Confirm reuse-surface target & register shard-wiki on it

```task
id: SHARD-WP-0013-T1
status: done
priority: high
state_hub_task_id: "603cef8d-6b58-4d30-9283-201dab0f5fe9"
```

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

```task
id: SHARD-WP-0013-T2
status: done
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
**reuse-surface-aligned capability taxonomy**: cluster UCs into **capabilities**; tag each UC
with the capability it realizes and whether it is **core vs. typed-extension** and **per-shard
activatable**; build a **conflict/overlap map** showing where requirements tension (e.g.
open-vs-governed, lossless-vs-lossy, live-vs-snapshot) and **how the framework mediates them**
(policy presets, capability gating, modes). This systematic structure is the bridge from demand
(UCs) to the engine's typed-extension model (T5). No UC is renumbered (stable IDs).

## Surface capability gaps / suggestions to the reuse surface

```task
id: SHARD-WP-0013-T3
status: done
priority: medium
state_hub_task_id: "06b62406-39e7-4227-bcc6-f9cab1c28996"
```

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)

```task
id: SHARD-WP-0013-T4
status: done
priority: high
state_hub_task_id: "1d0ef72b-2762-4086-9848-fde3b48c8454"
```

**Gate (Stability Note).** Amend `INTENT.md` to admit the engine *narrowly and additively*:
shard-wiki MAY provide a **native reference wiki-engine as a canonical-mode shard backend**
(small core + typed extensions), while remaining an orchestrator that neither mandates nor
replaces other engines (union-without-erasure preserved). Record a **ratified decision**
(`record_decision`/`resolve_decision`) capturing scope + the reconciliation. `WikiEngineCore
Architecture.md` (T5) is not authoritative until this lands. Mirror the precedent of the
auth-in-core amendment.

## Author spec/WikiEngineCoreArchitecture.md

```task
id: SHARD-WP-0013-T5
status: done
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; 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;
(e) traceability to UCs (T2) and the reuse surface (T1); (f) decisions/deferred/open + a
stability note. Elegance is the bar: fewest orthogonal core concepts, common case trivial,
exotic case possible (mirror the CoreArchitectureBlueprint discipline).

## Wire-up & close-out

```task
id: SHARD-WP-0013-T6
status: done
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`
(add `WikiEngineCoreArchitecture.md`); cross-link from `CoreArchitectureBlueprint.md`. Ensure
the reuse-surface registration + gap suggestions are synced. Final `check_repo_consistency`.

---

## Acceptance criteria

- shard-wiki is registered on the reuse surface with a capability profile + extension points;
  missing-feature suggestions are filed back to the reuse surface (tracked).
- `UseCaseCatalog.md` carries a systematic, reuse-surface-aligned capability structure (UC →
  capability, core/extension, per-shard-activatable, conflict-mediation map); no UC renumbered.
- INTENT is amended (additive engine = reference canonical-mode shard backend) with a ratified
  decision; the change is narrow and preserves orchestrator + union-without-erasure.
- `spec/WikiEngineCoreArchitecture.md` exists: small core + typed-extension framework, per-shard
  activation, integrated featureset with conflict mediation, engine-as-canonical-mode-shard,
  full UC + reuse-surface traceability, elegant.
- Each task committed; state-hub synced.

## Suggested task order

T1 reuse-surface (confirm + register) → T2 UC systematization → T3 gap suggestions →
T4 INTENT amendment + decision (gate) → T5 WikiEngineCoreArchitecture.md → T6 wire-up.