diff --git a/workplans/SHARD-WP-0013-wiki-engine-prep.md b/workplans/SHARD-WP-0013-wiki-engine-prep.md new file mode 100644 index 0000000..2cf6745 --- /dev/null +++ b/workplans/SHARD-WP-0013-wiki-engine-prep.md @@ -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.