shard-wiki/workplans/SHARD-WP-0001-yawex-requirements.md

---
id: SHARD-WP-0001
type: workplan
title: "shard-wiki requirements from yawex prior art"
domain: consumer
repo: shard-wiki
status: done
owner: tegwick
topic_slug: whynot
created: "2026-06-08"
updated: "2026-06-15"
state_hub_workstream_id: "0ed023a2-760b-4990-b931-8ee1f41ea08f"
---

# SHARD-WP-0001 — shard-wiki requirements from yawex prior art

## Goal

Turn the yawex (2004–05 Perl wiki engine) prior-art review into shard-wiki
requirements and design decisions. Produce federation-relevant specifications
that map onto `INTENT.md` without inheriting yawex's monolithic engine shape.

## Context

- Prior art: `research/260608-yawex-prior-art/sources/yawex-0.7.4/`
- Research findings: `research/260608-yawex-prior-art/findings.md`
- Architecture: `spec/ArchitectureBlueprint.md`
- Inbound demand: `demand/260608-netkingdom-integration-requirements.md`

Open architectural thread: a minimal authorization model in core revises an
INTENT non-goal and needs a ratified INTENT amendment before the access model
is treated as settled.

## Design federation page-resolution model

```task
id: SHARD-WP-0001-T1
status: done
priority: high
state_hub_task_id: "ebc036e4-1c3c-4e39-959b-1e37bc1049ad"
```

Design shard-wiki's cross-shard name resolution fresh. Use yawex's
LOCAL/CLIMB/DROP/GLOBAL/REMOTE/SWITCH/JUMP/VIRTUAL/FAILED states as a checklist
of cases to handle (especially REMOTE for remote shards and VIRTUAL for
projections), not as the interface. Decision 2026-06-08: inspiration only.

## Define namespace/path model and page+shard roles

```task
id: SHARD-WP-0001-T2
status: done
priority: high
state_hub_task_id: "431b4d28-3768-468f-b76f-4767f5aa1888"
```

Union path/namespace model with relative/absolute paths and normalization (from
yawex topics-as-dirs). Map page classes local/global/virtual to shard roles
canonical/cross-cutting/projected-computed.

## Specify union-level derived views

```task
id: SHARD-WP-0001-T3
status: done
priority: medium
state_hub_task_id: "564545ec-84f7-4c3d-a779-5b9c356919f4"
```

Decide which derived views are core vs adapter-provided: BackLinks,
RecentChanges, AllPages, SiteMap, Search. BackLinks (link-graph over the
federated union) is the strongest core candidate.

## Provenance and freshness model

```task
id: SHARD-WP-0001-T4
status: done
priority: medium
state_hub_task_id: "738326f5-b76c-4ecf-8843-7c762c3647d8"
```

Generalize yawex Page::info (modtime, TODO lasteditor/hits/edits) into
INTENT's explicit provenance: source shard, freshness, cached?, has-overlay?,
diverges-from?.

## Overlay / lightweight-patch model

```task
id: SHARD-WP-0001-T5
status: done
priority: medium
state_hub_task_id: "a268de6a-d1ef-4ed9-9828-c70991e1a772"
```

Non-destructive edits against remote/read-only shards as drafts/patches/overlays
before mutation (INTENT: overlay-before-mutation). Seeded by yawex's append +
threaded-comment workflow.

## Markdown link semantics

```task
id: SHARD-WP-0001-T6
status: done
priority: low
state_hub_task_id: "a7499f3e-911c-455b-afc3-eefc401eb60d"
```

TRANSFORM yawex CamelCase/[[free]]/red-? links into a CommonMark wikilink +
red-link extension. Open question: core vs reference-UI concern.

## Acceptance criteria

- Each task produces a written spec or ADR-ready design note in `spec/`.
- Designs honor INTENT boundaries: mechanism over policy, union without erasure,
  overlay before mutation, capability-aware adapters.
- Access-model and NetKingdom integration drafts are either ratified or explicitly
  deferred with tracked open questions.
- The next implementation workplan (domain model / adapter contract) can start
  without unresolved yawex-derived design gaps.