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

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

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

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

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

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)

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

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

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.