---
id: SHARD-WP-0013
type: workplan
title: "wiki-engine prep — reuse-surface registration, UC-catalog systematization, WikiEngineCoreArchitecture"
domain: whynot
repo: shard-wiki
status: active
owner: tegwick
topic_slug: whynot
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - SHARD-WP-0002
---

# 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: 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).

---

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

```task
id: SHARD-WP-0013-T1
status: todo
priority: high
```

**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.

## Systematize the UseCaseCatalog around a reuse-surface capability structure

```task
id: SHARD-WP-0013-T2
status: todo
priority: high
```

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: todo
priority: medium
```

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").

## INTENT amendment + ratified decision (additive engine = reference shard backend)

```task
id: SHARD-WP-0013-T4
status: todo
priority: high
```

**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: todo
priority: high
```

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
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: todo
priority: medium
```

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.