coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Promote c2 and yawex research into UseCaseCatalog (UC-01–UC-25)

Browse Source 
Organize 25 use cases across federation, collaboration, discovery, and
provenance. Include traceability tables mapping research IDs to catalog UCs.
This commit is contained in:
Bernd Worsch
2026-06-08 14:14:46 +02:00
parent 64b77f30c1
commit 5d8608aeae
4 changed files with 338 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SCOPE.md
View File

@@ -21,7 +21,7 @@ Learnings update both SCOPE and INTENT where necessary.
| Intent | `INTENT.md` established; authorization-in-core amendments drafted |
| Research | yawex prior art; c2 wiki origins (`research/260608-*/`) |
| Demand | NetKingdom integration asks captured, not yet negotiated |
| Spec | Access/history architecture blueprint drafted; PRD/TSD/UCC scaffolds |
| Spec | Architecture blueprint drafted; UseCaseCatalog 25 UCs from research; PRD/TSD scaffolds |
| Work | `SHARD-WP-0001` active — 6 design tasks, all todo |
## In Scope (today)

2
spec/README.md
View File

@@ -8,7 +8,7 @@ Background on document types: InfoTechPrimers on coulomb.social.
|------|--------|------|
| `ProductRequirementsDocument.md` | draft scaffold | What the product must deliver |
| `TechnicalSpecificationDocument.md` | draft scaffold | How the system is built |
| `UseCaseCatalog.md` | draft scaffold | Observable usage scenarios |
| `UseCaseCatalog.md` | draft | 25 use cases promoted from c2 + yawex research |
| `ArchitectureBlueprint.md` | draft | Access, history, and identity architecture |
Promote material from `research/` and reviewed items from `demand/` into spec

7
spec/TechnicalSpecificationDocument.md
View File

@@ -45,7 +45,12 @@ per information space.
Package scaffold only (`__version__`, smoke tests). Domain model not yet coded.
## 7. Next Specification Work
## 7. Use Cases
`spec/UseCaseCatalog.md` — 25 use cases (UC-01–UC-25) promoted from c2 wiki
origins and yawex prior-art research.
## 8. Next Specification Work
Outputs from `SHARD-WP-0001` tasks (page resolution, namespaces, derived views,
provenance, overlays, link semantics) will be incorporated here as they complete.

351
spec/UseCaseCatalog.md
View File

@@ -1,47 +1,356 @@
# UseCaseCatalog
Status: **draft scaffold** · Date: 2026-06-08
Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-08
Promoted from `research/260608-c2-wiki-origins/` and `research/260608-yawex-prior-art/`.
See InfoTechPrimers on coulomb.social for use-case catalog conventions.
## UC-01 — Standalone open wiki (L0)
## Conventions
Each use case lists:
- **Actor** — who initiates the action
- **Goal** — observable outcome
- **Source** — research lineage (`c2`, `yawex`, `intent`, or combined)
- **Notes** — shard-wiki-specific constraints or open design points
Priority hints: **MVP** = likely early value; **Later** = important but not first slice.
---
## A. Information space and federation
*shard-wiki orchestration scenarios (INTENT + yawex federation seeds).*
### UC-01 — Standalone open wiki (L0)
**Actor:** Anonymous contributor
**Goal:** Read and write wiki pages with full history and no external dependencies.
**Notes:** Ward Cunningham / c2-style open mode. Recovery via Git history, not gatekeeping.
**Source:** intent, c2
**Notes:** Ward Cunningham / c2-style open mode (`WhyWikiWorks`). Recovery via Git
history, not gatekeeping. Aligns with L0 in `spec/ArchitectureBlueprint.md`.
**Priority:** MVP
## UC-02 — Attach a Git repo shard
### UC-02 — Attach a shard to an information space
**Actor:** Maintainer
**Goal:** Attach a repository or `wiki/` subdirectory as a shard of an information space.
**Notes:** Preserve shard sovereignty and adapter capability profile.
**Goal:** Attach a repository, directory, or other backend as a shard of a root entity.
**Source:** intent, yawex
**Notes:** yawex `Conf::TestWiki / FriendsWiki` foreshadows multiple roots/shards.
Preserve shard sovereignty and adapter capability profile.
**Priority:** MVP
## UC-03 — Project a remote shard page locally
### UC-03 — Project a remote shard page locally
**Actor:** Reader
**Goal:** View a page from a remote or read-only shard as a local projection with provenance and freshness visible.
**Notes:** Lazy projection; no silent mutation.
**Goal:** View a page from a remote or read-only shard as a local projection with
provenance and freshness visible.
**Source:** intent, yawex
**Notes:** yawex `VIRTUAL` state = projection/cache. Lazy projection; no silent
mutation.
**Priority:** Later
## UC-04 — Overlay edit on read-only shard
### UC-04 — Overlay edit on read-only shard
**Actor:** Author
**Goal:** Propose changes to a remote/read-only page as overlay/draft/patch before destructive apply.
**Notes:** Overlay-before-mutation principle.
**Goal:** Propose changes to a remote/read-only page as overlay, draft, or patch
before destructive apply.
**Source:** intent, yawex
**Notes:** yawex append/comment workflow; c2 ThreadMode → refactor pattern.
Overlay-before-mutation principle.
**Priority:** Later
## UC-05 — Union browse (BackLinks, RecentChanges)
### UC-05 — Union derived views
**Actor:** Reader
**Goal:** Navigate derived views across all attached shards.
**Notes:** BackLinks over federated link graph is a strong core candidate (see research findings).
**Goal:** Navigate BackLinks, RecentChanges, AllPages, SiteMap, or Search across
all attached shards as a federated graph.
**Source:** intent, c2, yawex
**Notes:** Present on both c2 (community nerve center) and yawex core pages.
BackLinks over the union link-graph is the strongest core candidate; per-shard
vs union scope remains open (see UC-19–UC-21).
**Priority:** Later
## UC-06 — Authenticated team wiki (L2+)
### UC-06 — Authenticated team wiki (L2+)
**Actor:** Authenticated principal
**Goal:** Read/write under role-based authorization with identity from external provider.
**Notes:** See `spec/ArchitectureBlueprint.md` capability ladder.
**Goal:** Read and write under role-based authorization with identity from an
external provider.
**Source:** intent, yawex
**Notes:** yawex htpasswd + per-topic `AccessControl` is prior art only;
shard-wiki delegates authentication, owns authorization
(`spec/ArchitectureBlueprint.md`).
**Priority:** Later
## UC-07 — Detect cross-shard divergence
### UC-07 — Detect and reconcile cross-shard divergence
**Actor:** Maintainer
**Goal:** Identify when equivalent pages in different shards have diverged and reconcile.
**Notes:** Union without erasure — conflicts visible, not hidden.
**Goal:** Identify when equivalent pages in different shards have diverged and
reconcile them under explicit policy.
**Source:** intent
**Notes:** Union without erasure — conflicts visible, not hidden.
**Priority:** Later
---
## B. Knowledge work and collaboration
*Patterns from c2 social conventions and yawex authoring workflows.*
### UC-08 — Quick idea capture
**Actor:** Contributor
**Goal:** Capture a thought as a page and link to related pages, including ones
that do not exist yet.
**Source:** c2
**Notes:** c2 *incremental* and *open* design principles; Wiki = "quick web."
Markdown-first wikilink/red-link extension (yawex TRANSFORM) applies.
**Priority:** MVP
### UC-09 — Sandbox first edit
**Actor:** New contributor
**Goal:** Learn editing mechanics in a safe sandbox without affecting production
pages.
**Source:** c2
**Notes:** c2 `WikiWikiSandbox`, `WelcomeVisitors` onboarding path.
**Priority:** MVP
### UC-10 — Discussion to consensus document
**Actor:** Contributor (often acting as WikiMaster)
**Goal:** Refine a ThreadMode conversation into an unsigned DocumentMode page
that reflects community consensus.
**Source:** c2
**Notes:** ADD / EDIT / SPLIT / CAPTURE thread contributions; prefer rewrite
over stacked clarifications (`DocumentMode`, `GoodStyle`). Mechanism in core
vs reference UI TBD.
**Priority:** Later
### UC-11 — Distill experience into reusable knowledge
**Actor:** Practitioner
**Goal:** Turn field notes, threads, or project experience into durable,
reusable artifacts (patterns, methods, checklists).
**Source:** c2, yawex
**Notes:** c2 `PatternMode`, PPR "People, Projects & Patterns"; yawex blueprint
pages (UC-15). Not an encyclopedia (`WikiIsNotWikipedia`).
**Priority:** Later
### UC-12 — Practitioner field notes
**Actor:** Contributor
**Goal:** Maintain informal, subjective programming and project history that is
explicitly work-in-progress.
**Source:** c2
**Notes:** `InformalHistoryOfProgrammingIdeas`, `WorkInProgress`. Complements
UC-11; distinct from reference-grade documentation in `docs/` or `spec/`.
**Priority:** MVP
### UC-13 — Community presence
**Actor:** Visitor
**Goal:** Signal participation and discover who is active in the information
space.
**Source:** c2
**Notes:** c2 `RecentVisitors`, `PeopleIndex`. Optional attribution at L1+
(`ArchitectureBlueprint` L1 Attributed mode).
**Priority:** Later
### UC-14 — Self-curating knowledge base
**Actor:** Community
**Goal:** Improve collective quality through open editing, refactoring, and
convergent deduplication rather than gatekeeping.
**Source:** c2
**Notes:** `WhyWikiWorks`, `RefactorDontDelete`, `Convergent` design principle.
shard-wiki adds Git history as structural safety net beyond social norms.
**Priority:** MVP
### UC-15 — Create page from blueprint
**Actor:** Author
**Goal:** Instantiate a new page or topic structure from a template, duplicating
an agreed layout or subtree.
**Source:** yawex
**Notes:** yawex blueprint pages. Distinct from UC-08 (blank capture) and UC-10
(refactoring existing discussion).
**Priority:** Later
### UC-16 — Append or comment without full edit
**Actor:** Author
**Goal:** Add material to a page without replacing the entire body — lightweight
patch, comment, or append workflow.
**Source:** yawex, c2
**Notes:** yawex append/comment; c2 ThreadMode ADD. Maps to overlay model (UC-04)
for read-only/remote shards; direct append where adapter allows.
**Priority:** Later
---
## C. Discovery and navigation
*Derived views and browse patterns from c2 and yawex.*
### UC-17 — Change radar
**Actor:** Reader or maintainer
**Goal:** See what changed recently across pages and who changed it.
**Source:** c2, yawex
**Notes:** c2 `RecentChanges`, `QuickChanges`, `RecentChangesJunkie`; yawex
`RecentChanges` core page. Union scope in UC-05; this UC covers the user need
at any scope.
**Priority:** MVP
### UC-18 — BackLinks navigation
**Actor:** Reader
**Goal:** Find pages that link to the current page.
**Source:** c2, yawex
**Notes:** Link-graph query. Strong core candidate for federated union (UC-05).
**Priority:** Later
### UC-19 — All pages and site map browse
**Actor:** Reader
**Goal:** Survey the full page inventory or hierarchical site structure.
**Source:** c2, yawex
**Notes:** yawex `AllPages`, `SiteMap` core pages; c2 `WikiList`, categories,
`RoadMaps`. Namespace/path model affects presentation (UC-22).
**Priority:** Later
### UC-20 — Full-text search
**Actor:** Reader
**Goal:** Find pages by content keyword or phrase.
**Source:** c2, yawex
**Notes:** yawex `SearchPage`; c2 `FindPage`, `SearchHelper`. Core vs
adapter-provided indexing TBD.
**Priority:** Later
### UC-21 — Serendipitous browse
**Actor:** Reader
**Goal:** Discover unexpected relevant pages without a specific search target.
**Source:** c2
**Notes:** `RandomPages`, `VisualTour`, `LikePages`, `StartingPoints`.
**Priority:** Later
### UC-22 — Namespace and path navigation
**Actor:** Reader or author
**Goal:** Resolve and navigate pages using relative (`../`), absolute (`/`), and
normalized paths within a topic hierarchy.
**Source:** yawex
**Notes:** yawex topics-as-directories; page-resolution state space is
inspiration only for federation design (not inherited as API).
**Priority:** Later
### UC-23 — Soft topic creation via red link
**Actor:** Author
**Goal:** Follow a link to a nonexistent page and create it on first write.
**Source:** c2, yawex
**Notes:** c2 `PageName?`; yawex red-`?` link semantics. TRANSFORM to
CommonMark wikilink + red-link extension.
**Priority:** MVP
---
## D. Provenance and page metadata
*yawex `Page::info` and c2 attribution norms.*
### UC-24 — Inspect page provenance
**Actor:** Reader
**Goal:** See source shard, modification time, freshness, editor attribution,
edit count, and whether the page has local overlays or diverges elsewhere.
**Source:** yawex, c2, intent
**Notes:** yawex `Page::info`; c2 optional `UserName` signing. INTENT explicit
provenance principle.
**Priority:** Later
### UC-25 — Collaborative glossary and precise naming
**Actor:** Community
**Goal:** Build a shared vocabulary of precise page titles and linked terms that
reduce ambiguity across the information space.
**Source:** c2, yawex
**Notes:** c2 flat namespace + `WikiWord` / `Precise` principle; yawex
CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
**Priority:** Later
---
## Traceability
| UC | c2 research | yawex research | INTENT |
|----|-------------|----------------|--------|
| UC-01 | ✓ | | ✓ |
| UC-02 | | ✓ | ✓ |
| UC-03 | | ✓ | ✓ |
| UC-04 | ✓ | ✓ | ✓ |
| UC-05 | ✓ | ✓ | ✓ |
| UC-06 | | ✓ | ✓ |
| UC-07 | | | ✓ |
| UC-08 | ✓ | | |
| UC-09 | ✓ | | |
| UC-10 | ✓ | | |
| UC-11 | ✓ | ✓ | |
| UC-12 | ✓ | | |
| UC-13 | ✓ | | |
| UC-14 | ✓ | | ✓ |
| UC-15 | | ✓ | |
| UC-16 | ✓ | ✓ | |
| UC-17 | ✓ | ✓ | |
| UC-18 | ✓ | ✓ | |
| UC-19 | ✓ | ✓ | |
| UC-20 | ✓ | ✓ | |
| UC-21 | ✓ | | |
| UC-22 | | ✓ | |
| UC-23 | ✓ | ✓ | |
| UC-24 | ✓ | ✓ | ✓ |
| UC-25 | ✓ | ✓ | |
### c2 synthesis mapping
| Research ID | Catalog UC |
|-------------|------------|
| UC-C2-01 Quick idea capture | UC-08 |
| UC-C2-02 Collaborative glossary | UC-25 |
| UC-C2-03 Discussion → consensus doc | UC-10 |
| UC-C2-04 Pattern mining | UC-11 |
| UC-C2-05 Community guest book | UC-13 |
| UC-C2-06 Change radar | UC-17 |
| UC-C2-07 Self-curating knowledge base | UC-14 |
| UC-C2-08 Sandbox learning | UC-09 |
| UC-C2-09 Serendipitous browse | UC-21 |
| UC-C2-10 Practitioner field notes | UC-12 |
| UC-C2-11 Team memory for methods | UC-11, UC-12 |
| UC-C2-12 Soft creation of missing topics | UC-23 |
### yawex KEEP mapping
| yawex KEEP item | Catalog UC |
|-----------------|------------|
| Derived views (BackLinks, RecentChanges, AllPages, SiteMap, Search) | UC-05, UC-17–UC-20 |
| Topic = namespace hierarchy | UC-22 |
| Append/comment workflow | UC-04, UC-16 |
| Blueprint pages | UC-15 |
| Provenance hooks | UC-24 |
| Page classes (local/global/virtual) | UC-02, UC-03 (shard roles) |
| Wikilink / red-link semantics | UC-08, UC-23, UC-25 |
---
## Open questions
1. Which UC items are **MVP for L0 standalone** vs requiring federation or L2+?
2. Which derived views (UC-05, UC-17–UC-20) are **core orchestrator** vs
**adapter-provided**?
3. Do c2 collaboration patterns (UC-10, UC-14) belong in **core**, **reference
UI**, or **`wiki/` social convention** only?
4. Should UC-12 and `WikiIsNotWikipedia` be elevated into
`ProductRequirementsDocument.md` as explicit product identity?