generated from coulomb/repo-seed
workplan: SHARD-WP-0013 wiki-engine prep (reuse-surface, UC systematization, WikiEngineCoreArchitecture)
Prep for an additive native wiki-engine framed as shard-wiki's reference first-party shard backend (canonical-mode shard) — small core + typed-extension framework, per-shard activation, integrated featureset with conflict mediation. Tasks: confirm+register on the reuse surface; systematize the UC catalog around a reuse-surface capability taxonomy; surface capability gaps back; narrow INTENT amendment + ratified decision (gate); author WikiEngineCoreArchitecture.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
169
workplans/SHARD-WP-0013-wiki-engine-prep.md
Normal file
169
workplans/SHARD-WP-0013-wiki-engine-prep.md
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user