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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on
SHARD-WP-0013	workplan	wiki-engine prep — reuse-surface registration, UC-catalog systematization, WikiEngineCoreArchitecture	whynot	shard-wiki	active	tegwick	whynot	2026-06-15	2026-06-15	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

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

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

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)

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

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

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.