From 1c0c0efc56154167cf176c96a927cfd5261d3862 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 8 Jun 2026 13:55:27 +0200 Subject: [PATCH] Reorganize documentation into canonical repository layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt CoulombSocial/HelixForge/MarkiTect documentation structure: - research/260608-yawex-prior-art/ — yawex exploration and sources - demand/ — inbound NetKingdom integration requirements - spec/ — PRD, TSD, UseCaseCatalog, ArchitectureBlueprint scaffolds - docs/ — stakeholder documentation and repository-layout guide - wiki/, issues/, history/ — scaffolded directories Add SCOPE.md and AGENTS.md. Update workplan paths and README. --- .gitignore | 1 + AGENTS.md | 62 +++++++++++++++++++ CLAUDE.md | 2 +- README.md | 41 +++++++++++- SCOPE.md | 57 +++++++++++++++++ ...608-netkingdom-integration-requirements.md | 6 +- demand/README.md | 13 ++++ docs/README.md | 14 +++++ docs/repository-layout.md | 58 +++++++++++++++++ history/README.md | 8 +++ issues/README.md | 7 +++ research/260608-yawex-prior-art/README.md | 19 ++++++ .../260608-yawex-prior-art/findings.md | 2 +- .../sources}/yawex-0.7.4/README | 0 .../sources}/yawex-0.7.4/apache/README | 0 .../yawex-0.7.4/apache/httpd.conf.add | 0 .../sources}/yawex-0.7.4/apache/yawex.conf | 0 .../sources}/yawex-0.7.4/bin/yawex.pl | 0 .../yawex-0.7.4/javascript/wikimarkup.js | 0 .../sources}/yawex-0.7.4/makefile | 0 .../yawex-0.7.4/pages/CorePages/AllPages | 0 .../yawex-0.7.4/pages/CorePages/BackLinks | 0 .../yawex-0.7.4/pages/CorePages/CorePage | 0 .../yawex-0.7.4/pages/CorePages/CorePages | 0 .../yawex-0.7.4/pages/CorePages/NewPage | 0 .../yawex-0.7.4/pages/CorePages/RecentChanges | 0 .../yawex-0.7.4/pages/CorePages/SearchPage | 0 .../yawex-0.7.4/pages/CorePages/SiteMap | 0 .../yawex-0.7.4/pages/HelpPages/GlobalPage | 0 .../yawex-0.7.4/pages/HelpPages/HelpPage | 0 .../yawex-0.7.4/pages/HelpPages/HelpPages | 0 .../yawex-0.7.4/pages/SubContext/SubContext | 0 .../pages/SubContext/SubContextPage | 0 .../SubContext/SubSubContext/SubSubContext | 0 .../sources}/yawex-0.7.4/pages/TopLevelPage | 0 .../yawex-0.7.4/pages/UserPages/BerndWorsch | 0 .../yawex-0.7.4/pages/UserPages/UserPages | 0 .../sources}/yawex-0.7.4/pages/WelcomePage | 0 .../sources}/yawex-0.7.4/templates/htaccess | 0 .../yawex-0.7.4/templates/template-devel.html | 0 .../templates/template-gila-colors.css | 0 .../yawex-0.7.4/templates/template-gila.css | 0 .../yawex-0.7.4/templates/template-gila.html | 0 .../templates/template-neurobotik.html | 0 .../sources}/yawex-0.7.4/tools/striptests | 0 research/README.md | 13 ++++ .../ArchitectureBlueprint.md | 8 ++- spec/ProductRequirementsDocument.md | 54 ++++++++++++++++ spec/README.md | 15 +++++ spec/TechnicalSpecificationDocument.md | 51 +++++++++++++++ spec/UseCaseCatalog.md | 47 ++++++++++++++ wiki/README.md | 7 +++ workplans/SHARD-WP-0001-yawex-requirements.md | 10 +-- 53 files changed, 483 insertions(+), 12 deletions(-) create mode 100644 AGENTS.md create mode 100644 SCOPE.md rename docs/requirements-user-engine-netkingdom.md => demand/260608-netkingdom-integration-requirements.md (95%) create mode 100644 demand/README.md create mode 100644 docs/README.md create mode 100644 docs/repository-layout.md create mode 100644 history/README.md create mode 100644 issues/README.md create mode 100644 research/260608-yawex-prior-art/README.md rename docs/requirements-from-yawex.md => research/260608-yawex-prior-art/findings.md (98%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/README (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/apache/README (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/apache/httpd.conf.add (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/apache/yawex.conf (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/bin/yawex.pl (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/javascript/wikimarkup.js (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/makefile (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/AllPages (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/BackLinks (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/CorePage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/CorePages (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/NewPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/RecentChanges (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/SearchPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/CorePages/SiteMap (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/HelpPages/GlobalPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/HelpPages/HelpPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/HelpPages/HelpPages (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/SubContext/SubContext (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/SubContext/SubContextPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/SubContext/SubSubContext/SubSubContext (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/TopLevelPage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/UserPages/BerndWorsch (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/UserPages/UserPages (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/pages/WelcomePage (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/htaccess (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/template-devel.html (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/template-gila-colors.css (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/template-gila.css (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/template-gila.html (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/templates/template-neurobotik.html (100%) rename {history/priorart => research/260608-yawex-prior-art/sources}/yawex-0.7.4/tools/striptests (100%) create mode 100644 research/README.md rename docs/access-model-blueprint.md => spec/ArchitectureBlueprint.md (97%) create mode 100644 spec/ProductRequirementsDocument.md create mode 100644 spec/README.md create mode 100644 spec/TechnicalSpecificationDocument.md create mode 100644 spec/UseCaseCatalog.md create mode 100644 wiki/README.md diff --git a/.gitignore b/.gitignore index 36b13f1..ab4272b 100644 --- a/.gitignore +++ b/.gitignore @@ -174,3 +174,4 @@ cython_debug/ # PyPI configuration file .pypirc +agent-tools/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ff504ab --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md + +Guidance for agents working in `shard-wiki`. + +## Read First + +1. `INTENT.md` — aspiration and boundaries (stable; architectural changes are rare). +2. `SCOPE.md` — what we are achieving now and current maturity. +3. `.custodian-brief.md` — State Hub snapshot (generated; do not edit manually). + +## Documentation Layout + +This repo follows the CoulombSocial / HelixForge / MarkiTect documentation +layout (recommendation, not strict law). Efficient retrieval by purpose: + +| Path | Purpose | +|------|---------| +| `INTENT.md` | Aspiration and boundaries | +| `SCOPE.md` | Top-level view of current achievement; closes gap to INTENT | +| `research/` | Exploration results (`yymmdd-` prefix on files or subdirs) | +| `demand/` | Inbound requests not yet reviewed into spec or workplans | +| `spec/` | Implementation guardrails (PRD, TSD, use cases, architecture) | +| `workplans/` | State Hub–registered implementation tasks | +| `docs/` | Stakeholder documentation (users, developers, humans, agents) | +| `wiki/` | Perspective-free interconnected knowledge (wiki UI when connected) | +| `issues/` | Mirror of relevant open tickets when ticket systems are in use | +| `history/` | Archived material (`yymmdd-` prefix); out of scope for daily work | + +**Mode of operation:** close SCOPE → INTENT while learning; refine both as needed. + +## Domain Vocabulary + +Honor terms from `INTENT.md`: shard, root entity, adapter contract, projection, +overlay, coordination journal, shard modes. Do not invent parallel vocabulary. + +## Build And Test + +```bash +pip install -e ".[dev]" +pytest +ruff check +ruff format +``` + +## State Hub + +Workplans register with State Hub. After workplan changes: + +```bash +cd ~/state-hub && make fix-consistency REPO=shard-wiki +``` + +Finished or canceled workplans move to `history/` with a `yymmdd-` archive prefix. + +## Where To Put New Material + +- Exploratory analysis → `research/yymmdd-/` +- Raw feature ask or external requirement → `demand/` +- Reviewed design ready to guide code → `spec/` +- Implementation tasks → `workplans/` +- User/dev/agent how-to → `docs/` +- Collaborative unstructured notes → `wiki/` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 688e2db..1807be9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository status -This is an **early-stage Python repository**. The package scaffold (`src/shard_wiki/`, `tests/`, `pyproject.toml`) exists with only smoke tests — the domain model is not yet implemented. Read `INTENT.md` in full before designing anything; it is the authoritative specification of what this repository is and is not. You are still establishing conventions, so keep new code consistent with the domain vocabulary below. +This is an **early-stage Python repository**. The package scaffold (`src/shard_wiki/`, `tests/`, `pyproject.toml`) exists with only smoke tests — the domain model is not yet implemented. Read `INTENT.md` (aspiration), `SCOPE.md` (current achievement), and `AGENTS.md` (layout and conventions) before designing anything. Close the gap from SCOPE to INTENT via `research/`, `spec/`, and `workplans/`. ## What this project is diff --git a/README.md b/README.md index c94f848..ac8f18e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,41 @@ -Git based markdown wiki orchestrator +# shard-wiki +Git-based Markdown wiki orchestrator and federation layer. + +`shard-wiki` joins heterogeneous wiki-shaped page stores (**shards**) into a +coherent information space while preserving provenance, capabilities, and +history. It is an orchestration layer, not a wiki engine. + +## Status + +Early-stage: Python scaffold, intent and specification groundwork, active design +workplan. See `SCOPE.md` for current maturity. + +## Documentation + +| Document | Purpose | +|----------|---------| +| [INTENT.md](INTENT.md) | Aspiration and boundaries | +| [SCOPE.md](SCOPE.md) | What we achieve now | +| [AGENTS.md](AGENTS.md) | Agent working guide | +| [docs/repository-layout.md](docs/repository-layout.md) | How this repo organizes information | + +## Quick start + +```bash +pip install -e ".[dev]" +pytest +``` + +## Layout + +``` +research/ explorations (yymmdd-prefixed) +demand/ inbound unreviewed requirements +spec/ implementation specifications +workplans/ State Hub–registered tasks +docs/ stakeholder documentation +wiki/ collaborative knowledge (wiki UI when connected) +issues/ ticket mirrors +history/ archived material (yymmdd-prefixed) +``` \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..169466b --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,57 @@ +# SCOPE + +## One-Liner + +Git-based Markdown wiki orchestrator and federation layer — early-stage scaffold +with intent, research, and specification groundwork; domain model not yet +implemented. + +## Mode Of Operation + +Close the gap between this file and `INTENT.md` by exploring the problem space +(`research/`), reviewing inbound demand (`demand/`), refining specifications +(`spec/`), and implementing through registered workplans (`workplans/`). +Learnings update both SCOPE and INTENT where necessary. + +## Current Status + +| Layer | State | +|-------|-------| +| Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) | +| Intent | `INTENT.md` established; authorization-in-core amendments drafted | +| Research | yawex prior-art exploration (`research/260608-yawex-prior-art/`) | +| Demand | NetKingdom integration asks captured, not yet negotiated | +| Spec | Access/history architecture blueprint drafted; PRD/TSD/UCC scaffolds | +| Work | `SHARD-WP-0001` active — 6 design tasks, all todo | + +## In Scope (today) + +- Establishing repository documentation structure and specification groundwork. +- Federation design informed by yawex prior art (page resolution, namespaces, + derived views, provenance, overlays). +- Authorization model design (delegated authentication, core authorization). +- Shard adapter contract and wiki page model (to be specified, then implemented). +- Git-backed coordination journal for information spaces. +- State Hub workplan registration and consistency sync. + +## Out Of Scope (today) + +- A standalone wiki engine UI or rendering pipeline. +- Authentication, credential storage, or user directory implementation. +- Hard-coded editorial, sync, or conflict-resolution policy. +- Generic file mirroring independent of wiki-page semantics. +- Production deployment, multi-tenant operations, or enterprise IAM rollout. + +## Boundary Rule + +`shard-wiki` orchestrates wiki-shaped content across heterogeneous shards. It +provides mechanisms (federation, projection, overlay, patching, reconciliation); +policy (canonical source, conflict preference, access rules) remains explicit and +configurable. Identity comes from pluggable providers; authorization decisions +live in core. + +## Current Planning + +Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md`. +Specification outputs from that workplan land in `spec/`. Inbound integration +asks remain in `demand/` until reviewed and promoted into spec or workplans. \ No newline at end of file diff --git a/docs/requirements-user-engine-netkingdom.md b/demand/260608-netkingdom-integration-requirements.md similarity index 95% rename from docs/requirements-user-engine-netkingdom.md rename to demand/260608-netkingdom-integration-requirements.md index 2384429..08f7f59 100644 --- a/docs/requirements-user-engine-netkingdom.md +++ b/demand/260608-netkingdom-integration-requirements.md @@ -1,8 +1,10 @@ # Requirements — what shard-wiki needs from user-engine & net-kingdom -Status: **draft for review** · Date: 2026-06-08 +Status: **inbound demand — draft for review** · Date: 2026-06-08 -Derived from `access-model-blueprint.md`. These are the integration contracts shard-wiki +Located in `demand/` — not yet promoted to `spec/` or workplans. + +Derived from `spec/ArchitectureBlueprint.md`. These are the integration contracts shard-wiki needs to climb from L0 (open, standalone) to L4 (multi-tenant enterprise) **without changing its core**. They are requirements *on* the NetKingdom domain repos, to be negotiated with their owners — not assumptions about their current implementation. diff --git a/demand/README.md b/demand/README.md new file mode 100644 index 0000000..891bba5 --- /dev/null +++ b/demand/README.md @@ -0,0 +1,13 @@ +# demand/ + +Inbound feature requests, requirements, suggestions, and improvement +opportunities that have **not** been systematically reviewed and captured in +`spec/` or `workplans/`. + +Material here may be raw and needs scrutiny before implementation picks it up. + +## Current Items + +| Date | File | Summary | +|------|------|---------| +| 2026-06-08 | `260608-netkingdom-integration-requirements.md` | Integration contracts needed from user-engine and net-kingdom for L2–L4 access modes | \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..60e877b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# docs/ + +Stakeholder-facing documentation for users, developers, humans, and agents. + +Rewrite docs when they become wrong or stale — they should reflect what the +repo actually does. + +| Document | Audience | +|----------|----------| +| `repository-layout.md` | All — how documentation is organized in this repo | +| `../README.md` | New visitors — project entry point | +| `../AGENTS.md` | Agents — working conventions and layout | +| `../INTENT.md` | Architects — aspiration and boundaries | +| `../SCOPE.md` | Contributors — current achievement and planning | \ No newline at end of file diff --git a/docs/repository-layout.md b/docs/repository-layout.md new file mode 100644 index 0000000..90b4989 --- /dev/null +++ b/docs/repository-layout.md @@ -0,0 +1,58 @@ +# Repository documentation layout + +This repository follows the CoulombSocial / HelixForge / MarkiTect documentation +layout. It is a **recommendation** for efficient information retrieval, not a +strict law. + +## Operating model + +- `INTENT.md` captures aspiration and boundaries. +- `SCOPE.md` captures a top-level view of what we achieve. +- Work closes the gap from SCOPE to INTENT while learning and refining both. + +## Directories + +### `research/` + +Exploration results in the problem and solution space. Use a `yymmdd-` prefix +on markdown files or subdirectories when multiple files or sources are involved. + +### `demand/` + +Inbound feature requests, requirements, and suggestions not yet reviewed into +`spec/` or `workplans/`. Raw material — needs scrutiny before implementation. + +### `spec/` + +Implementation guardrails. Typical files: + +- `ProductRequirementsDocument.md` +- `TechnicalSpecificationDocument.md` +- `UseCaseCatalog.md` +- `ArchitectureBlueprint.md` + +Background: InfoTechPrimers on coulomb.social. + +### `workplans/` + +State Hub–registered workplans with implementation tasks. Finished or canceled +workplans move to `history/` with a `yymmdd-` archive prefix. + +### `docs/` + +Stakeholder documentation (this directory). + +### `wiki/` + +Interconnected collective knowledge without a single perspective. Powerful when +connected to a wiki UI for creators, users, and investors. + +### `issues/` + +Optional mirror of relevant open tickets from customer support, dev-sec-ops, or +other ticket systems. + +### `history/` + +Archived material no longer needed for daily work. Use `yymmdd-` prefixes. +Consult only for research or diagnostics. \ No newline at end of file diff --git a/history/README.md b/history/README.md new file mode 100644 index 0000000..1626472 --- /dev/null +++ b/history/README.md @@ -0,0 +1,8 @@ +# history/ + +Archived material that is no longer needed for daily work but should be kept. + +Use a `yymmdd-` prefix when archiving files or directories. Content here is +**out of scope** for regular tasks — consult only for research or diagnostics. + +Finished or canceled workplans from `workplans/` are archived here. \ No newline at end of file diff --git a/issues/README.md b/issues/README.md new file mode 100644 index 0000000..d0c04f6 --- /dev/null +++ b/issues/README.md @@ -0,0 +1,7 @@ +# issues/ + +Optional mirror of relevant open tickets from customer support, dev-sec-ops, or +other work-organization systems. + +No mirrored issues yet. When ticket systems are in use, copy or link relevant +open items here for easier repository-local access. \ No newline at end of file diff --git a/research/260608-yawex-prior-art/README.md b/research/260608-yawex-prior-art/README.md new file mode 100644 index 0000000..577a68c --- /dev/null +++ b/research/260608-yawex-prior-art/README.md @@ -0,0 +1,19 @@ +# 260608 — yawex prior art exploration + +Date: 2026-06-08 + +## What this is + +Review of **yawex 0.7.4** (2004–05 filesystem-backed CGI/Perl wiki engine) as +prior art for `shard-wiki` federation design. + +## Contents + +| Path | Role | +|------|------| +| `findings.md` | Distilled KEEP / TRANSFORM / DROP analysis and open questions | +| `sources/yawex-0.7.4/` | Original prior-art tree (Perl engine, pages, templates) | + +## Status + +Exploration complete. Design tasks tracked in `workplans/SHARD-WP-0001`. \ No newline at end of file diff --git a/docs/requirements-from-yawex.md b/research/260608-yawex-prior-art/findings.md similarity index 98% rename from docs/requirements-from-yawex.md rename to research/260608-yawex-prior-art/findings.md index dcd8c0b..15fc7a8 100644 --- a/docs/requirements-from-yawex.md +++ b/research/260608-yawex-prior-art/findings.md @@ -1,6 +1,6 @@ # Requirements seed — review of yawex prior art -Source: `history/priorart/yawex-0.7.4/` — a filesystem-backed CGI/Perl wiki engine +Source: `research/260608-yawex-prior-art/sources/yawex-0.7.4/` — a filesystem-backed CGI/Perl wiki engine (2004–2005, "Yet Another Wiki engine eXtended"). This document distills that prior art into requirements for `shard-wiki`, the Markdown-first, Git-backed wiki **federation/orchestration layer** described in `INTENT.md`. diff --git a/history/priorart/yawex-0.7.4/README b/research/260608-yawex-prior-art/sources/yawex-0.7.4/README similarity index 100% rename from history/priorart/yawex-0.7.4/README rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/README diff --git a/history/priorart/yawex-0.7.4/apache/README b/research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/README similarity index 100% rename from history/priorart/yawex-0.7.4/apache/README rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/README diff --git a/history/priorart/yawex-0.7.4/apache/httpd.conf.add b/research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/httpd.conf.add similarity index 100% rename from history/priorart/yawex-0.7.4/apache/httpd.conf.add rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/httpd.conf.add diff --git a/history/priorart/yawex-0.7.4/apache/yawex.conf b/research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/yawex.conf similarity index 100% rename from history/priorart/yawex-0.7.4/apache/yawex.conf rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/apache/yawex.conf diff --git a/history/priorart/yawex-0.7.4/bin/yawex.pl b/research/260608-yawex-prior-art/sources/yawex-0.7.4/bin/yawex.pl similarity index 100% rename from history/priorart/yawex-0.7.4/bin/yawex.pl rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/bin/yawex.pl diff --git a/history/priorart/yawex-0.7.4/javascript/wikimarkup.js b/research/260608-yawex-prior-art/sources/yawex-0.7.4/javascript/wikimarkup.js similarity index 100% rename from history/priorart/yawex-0.7.4/javascript/wikimarkup.js rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/javascript/wikimarkup.js diff --git a/history/priorart/yawex-0.7.4/makefile b/research/260608-yawex-prior-art/sources/yawex-0.7.4/makefile similarity index 100% rename from history/priorart/yawex-0.7.4/makefile rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/makefile diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/AllPages b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/AllPages similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/AllPages rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/AllPages diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/BackLinks b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/BackLinks similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/BackLinks rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/BackLinks diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/CorePage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/CorePage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/CorePage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/CorePage diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/CorePages b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/CorePages similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/CorePages rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/CorePages diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/NewPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/NewPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/NewPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/NewPage diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/RecentChanges b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/RecentChanges similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/RecentChanges rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/RecentChanges diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/SearchPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/SearchPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/SearchPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/SearchPage diff --git a/history/priorart/yawex-0.7.4/pages/CorePages/SiteMap b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/SiteMap similarity index 100% rename from history/priorart/yawex-0.7.4/pages/CorePages/SiteMap rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/CorePages/SiteMap diff --git a/history/priorart/yawex-0.7.4/pages/HelpPages/GlobalPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/GlobalPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/HelpPages/GlobalPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/GlobalPage diff --git a/history/priorart/yawex-0.7.4/pages/HelpPages/HelpPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/HelpPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/HelpPages/HelpPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/HelpPage diff --git a/history/priorart/yawex-0.7.4/pages/HelpPages/HelpPages b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/HelpPages similarity index 100% rename from history/priorart/yawex-0.7.4/pages/HelpPages/HelpPages rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/HelpPages/HelpPages diff --git a/history/priorart/yawex-0.7.4/pages/SubContext/SubContext b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubContext similarity index 100% rename from history/priorart/yawex-0.7.4/pages/SubContext/SubContext rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubContext diff --git a/history/priorart/yawex-0.7.4/pages/SubContext/SubContextPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubContextPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/SubContext/SubContextPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubContextPage diff --git a/history/priorart/yawex-0.7.4/pages/SubContext/SubSubContext/SubSubContext b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubSubContext/SubSubContext similarity index 100% rename from history/priorart/yawex-0.7.4/pages/SubContext/SubSubContext/SubSubContext rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/SubContext/SubSubContext/SubSubContext diff --git a/history/priorart/yawex-0.7.4/pages/TopLevelPage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/TopLevelPage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/TopLevelPage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/TopLevelPage diff --git a/history/priorart/yawex-0.7.4/pages/UserPages/BerndWorsch b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/UserPages/BerndWorsch similarity index 100% rename from history/priorart/yawex-0.7.4/pages/UserPages/BerndWorsch rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/UserPages/BerndWorsch diff --git a/history/priorart/yawex-0.7.4/pages/UserPages/UserPages b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/UserPages/UserPages similarity index 100% rename from history/priorart/yawex-0.7.4/pages/UserPages/UserPages rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/UserPages/UserPages diff --git a/history/priorart/yawex-0.7.4/pages/WelcomePage b/research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/WelcomePage similarity index 100% rename from history/priorart/yawex-0.7.4/pages/WelcomePage rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/pages/WelcomePage diff --git a/history/priorart/yawex-0.7.4/templates/htaccess b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/htaccess similarity index 100% rename from history/priorart/yawex-0.7.4/templates/htaccess rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/htaccess diff --git a/history/priorart/yawex-0.7.4/templates/template-devel.html b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-devel.html similarity index 100% rename from history/priorart/yawex-0.7.4/templates/template-devel.html rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-devel.html diff --git a/history/priorart/yawex-0.7.4/templates/template-gila-colors.css b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila-colors.css similarity index 100% rename from history/priorart/yawex-0.7.4/templates/template-gila-colors.css rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila-colors.css diff --git a/history/priorart/yawex-0.7.4/templates/template-gila.css b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila.css similarity index 100% rename from history/priorart/yawex-0.7.4/templates/template-gila.css rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila.css diff --git a/history/priorart/yawex-0.7.4/templates/template-gila.html b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila.html similarity index 100% rename from history/priorart/yawex-0.7.4/templates/template-gila.html rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-gila.html diff --git a/history/priorart/yawex-0.7.4/templates/template-neurobotik.html b/research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-neurobotik.html similarity index 100% rename from history/priorart/yawex-0.7.4/templates/template-neurobotik.html rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/templates/template-neurobotik.html diff --git a/history/priorart/yawex-0.7.4/tools/striptests b/research/260608-yawex-prior-art/sources/yawex-0.7.4/tools/striptests similarity index 100% rename from history/priorart/yawex-0.7.4/tools/striptests rename to research/260608-yawex-prior-art/sources/yawex-0.7.4/tools/striptests diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..3f6b169 --- /dev/null +++ b/research/README.md @@ -0,0 +1,13 @@ +# research/ + +Exploration results for the problem and solution space. + +Each exploration uses a `yymmdd-` prefix on the markdown file or subdirectory +when multiple files or sources are involved. Findings here inform `spec/` and +`SCOPE.md`; they do not directly authorize implementation until promoted. + +## Active Explorations + +| Date | Path | Summary | +|------|------|---------| +| 2026-06-08 | `260608-yawex-prior-art/` | yawex 0.7.4 Perl wiki prior art; federation design seeds | \ No newline at end of file diff --git a/docs/access-model-blueprint.md b/spec/ArchitectureBlueprint.md similarity index 97% rename from docs/access-model-blueprint.md rename to spec/ArchitectureBlueprint.md index 53c0549..51eb5d2 100644 --- a/docs/access-model-blueprint.md +++ b/spec/ArchitectureBlueprint.md @@ -1,8 +1,11 @@ -# Architecture blueprint — shard-wiki access & history model +# ArchitectureBlueprint — shard-wiki access & history model Status: **draft for review** · Date: 2026-06-08 · Resolves pending decision "Scope of a minimal access model in shard-wiki core". +Part of `spec/`. Background on specification document types: InfoTechPrimers on +coulomb.social. + This blueprint settles how shard-wiki handles access control and change history. It realizes the INTENT principles *Open by default, progressively governed*, *History as the safety net*, and *Authorization in core, authentication delegated*. @@ -142,4 +145,5 @@ identical; only the gate differs. 4. How tenant ↔ root-entity mapping is configured and discovered. 5. Whether L1 "attributed but open" is worth shipping or we jump L0 → L2. -See `requirements-user-engine-netkingdom.md` for the concrete asks these imply. +See `demand/260608-netkingdom-integration-requirements.md` for the concrete asks +these imply. diff --git a/spec/ProductRequirementsDocument.md b/spec/ProductRequirementsDocument.md new file mode 100644 index 0000000..29c976f --- /dev/null +++ b/spec/ProductRequirementsDocument.md @@ -0,0 +1,54 @@ +# ProductRequirementsDocument + +Status: **draft scaffold** · Date: 2026-06-08 + +See InfoTechPrimers on coulomb.social for PRD conventions. + +## 1. Product Name + +**shard-wiki** + +## 2. Product Intent + +Git-based Markdown wiki **orchestrator and federation layer** — not a wiki +engine. Joins heterogeneous wiki-shaped page stores (shards) into a coherent +information space while preserving provenance, capabilities, and history. + +Authoritative aspiration: `INTENT.md`. + +## 3. Problem Statement + +Wiki content lives in fragmented backends (Git repos, Gitea wikis, local +folders, Obsidian vaults, WebDAV, application databases). Users and tools need a +union of pages with versionable coordination, overlays for remote edits, and +explicit provenance — without forcing a single storage format or engine. + +## 4. Target Users + +See `INTENT.md` § Intended Users. + +## 5. Core Capabilities (maturity target) + +- Attach multiple shards to a shared root entity. +- Present union views of pages, links, metadata, and revisions. +- Lazy projection and cache of remote shard content. +- Overlay-before-mutation for capability-limited shards. +- Git-backed coordination journal per information space. +- Capability-aware shard adapter contract. +- Pluggable authorization from open (L0) through multi-tenant enterprise (L4). +- Complete recoverable history as the baseline safety net. + +## 6. Non-Goals + +See `INTENT.md` § Strategic Boundaries. + +## 7. Research Inputs + +- `research/260608-yawex-prior-art/findings.md` — federation design seeds from + prior art. + +## 8. Open Items + +Pending completion of `SHARD-WP-0001` design tasks and ratification of access +model INTENT amendments. Detailed requirements will be expanded as spec tasks +complete. \ No newline at end of file diff --git a/spec/README.md b/spec/README.md new file mode 100644 index 0000000..5e542cb --- /dev/null +++ b/spec/README.md @@ -0,0 +1,15 @@ +# spec/ + +Specification files that guide and guardrail implementation. + +Background on document types: InfoTechPrimers on coulomb.social. + +| File | Status | Role | +|------|--------|------| +| `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 | +| `ArchitectureBlueprint.md` | draft | Access, history, and identity architecture | + +Promote material from `research/` and reviewed items from `demand/` into spec +before treating it as implementation authority. \ No newline at end of file diff --git a/spec/TechnicalSpecificationDocument.md b/spec/TechnicalSpecificationDocument.md new file mode 100644 index 0000000..6487e20 --- /dev/null +++ b/spec/TechnicalSpecificationDocument.md @@ -0,0 +1,51 @@ +# TechnicalSpecificationDocument + +Status: **draft scaffold** · Date: 2026-06-08 + +See InfoTechPrimers on coulomb.social for TSD conventions. + +## 1. System Overview + +Python package (`src/shard_wiki/`) implementing a federation orchestration +layer. Markdown-first, backend-neutral page model. Git-addressable coordination +per information space. + +## 2. Implementation Stack + +| Concern | Choice | +|---------|--------| +| Language | Python ≥ 3.11 | +| Layout | `src/` package, hatchling build | +| Tests | pytest | +| Lint/format | ruff | + +## 3. Core Abstractions (to be specified) + +| Abstraction | Description | +|-------------|-------------| +| Shard | Independently meaningful page store with sovereignty | +| Root entity | Joined information space shards attach to | +| Shard adapter contract | Versioned, capability-aware backend interface | +| Wiki page model | Paths, links, metadata, revisions | +| Projection | Lazy local view of remote content | +| Overlay | Non-destructive edit before remote mutation | +| Coordination journal | Git-backed change record | + +## 4. Architecture References + +- `spec/ArchitectureBlueprint.md` — access, history, identity delegation + +## 5. Integration Boundaries + +- Authentication delegated to external identity provider (reference: + net-kingdom + user-engine). See `demand/260608-netkingdom-integration-requirements.md`. +- No credential or secret storage in shard-wiki core. + +## 6. Current Implementation + +Package scaffold only (`__version__`, smoke tests). Domain model not yet coded. + +## 7. 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. \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md new file mode 100644 index 0000000..aa87bd2 --- /dev/null +++ b/spec/UseCaseCatalog.md @@ -0,0 +1,47 @@ +# UseCaseCatalog + +Status: **draft scaffold** · Date: 2026-06-08 + +See InfoTechPrimers on coulomb.social for use-case catalog conventions. + +## 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. + +## UC-02 — Attach a Git repo shard + +**Actor:** Maintainer +**Goal:** Attach a repository or `wiki/` subdirectory as a shard of an information space. +**Notes:** Preserve shard sovereignty and adapter capability profile. + +## 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. + +## 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. + +## UC-05 — Union browse (BackLinks, RecentChanges) + +**Actor:** Reader +**Goal:** Navigate derived views across all attached shards. +**Notes:** BackLinks over federated link graph is a strong core candidate (see research findings). + +## 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. + +## UC-07 — Detect 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. \ No newline at end of file diff --git a/wiki/README.md b/wiki/README.md new file mode 100644 index 0000000..b6a09f6 --- /dev/null +++ b/wiki/README.md @@ -0,0 +1,7 @@ +# wiki/ + +Perspective-free interconnected knowledge for this repository. + +This directory is intended for collaborative wiki content when a wiki UI is +connected. Until then, use `docs/` for stakeholder-facing documentation and +`research/` for structured explorations. \ No newline at end of file diff --git a/workplans/SHARD-WP-0001-yawex-requirements.md b/workplans/SHARD-WP-0001-yawex-requirements.md index ba92278..c2df110 100644 --- a/workplans/SHARD-WP-0001-yawex-requirements.md +++ b/workplans/SHARD-WP-0001-yawex-requirements.md @@ -22,10 +22,10 @@ that map onto `INTENT.md` without inheriting yawex's monolithic engine shape. ## Context -- Prior art: `history/priorart/yawex-0.7.4/` -- Requirements seed: `docs/requirements-from-yawex.md` -- Access model draft: `docs/access-model-blueprint.md` -- NetKingdom integration draft: `docs/requirements-user-engine-netkingdom.md` +- 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 @@ -111,7 +111,7 @@ red-link extension. Open question: core vs reference-UI concern. ## Acceptance criteria -- Each task produces a written spec or ADR-ready design note in `docs/`. +- 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