diff --git a/docker-compose.yml b/docker-compose.yml index 9aa98ce..58711e3 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -83,6 +83,24 @@ services: networks: - spore-internal + # ============================================================ + # Spore Site (Quartz — governance knowledge garden) + # ============================================================ + spore-site: + build: + context: ./site + dockerfile: Dockerfile + container_name: spore-site + restart: unless-stopped + labels: + - "traefik.enable=true" + - "traefik.http.routers.spore-site.rule=Host(`spore.jeffemmett.com`)" + - "traefik.http.routers.spore-site.entrypoints=web" + - "traefik.http.services.spore-site.loadbalancer.server.port=80" + - "traefik.docker.network=traefik-public" + networks: + - traefik-public + volumes: node_data: postgres_data: diff --git a/site/Dockerfile b/site/Dockerfile new file mode 100644 index 0000000..54c3cf7 --- /dev/null +++ b/site/Dockerfile @@ -0,0 +1,18 @@ +FROM node:22-slim AS builder + +WORKDIR /usr/src/app + +# Clone Quartz and install deps +RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/* +RUN git clone --depth 1 https://github.com/jackyzha0/quartz.git . && npm ci + +# Copy content +COPY content/ /usr/src/app/content/ + +# Build static site +RUN npx quartz build + +# --- Serve with lightweight nginx --- +FROM nginx:alpine +COPY --from=builder /usr/src/app/public /usr/share/nginx/html +EXPOSE 80 diff --git a/site/content/claims.md b/site/content/claims.md new file mode 100644 index 0000000..fd06777 --- /dev/null +++ b/site/content/claims.md @@ -0,0 +1,48 @@ +--- +title: Claims & Evidence +--- + +# Claims & Evidence + +The Claims-Evidence-Attestation (CEA) system enables collaborative knowledge building with verifiable provenance. + +## Claims + +A claim is a knowledge assertion proposed by a holon. Claims follow a lifecycle: + +``` +proposed → supported → challenged → superseded +``` + +Each claim has a confidence score (0.0–1.0) and can accumulate evidence and attestations over time. + +## Evidence + +Evidence can **support** or **challenge** a claim. Each piece of evidence includes: +- Body text describing the evidence +- Relation type (`supports` or `challenges`) +- Provenance metadata (source attribution) + +## Attestations + +Holons can attest to claims with three verdicts: +- **endorse** — Agreement with the claim +- **dispute** — Disagreement with the claim +- **abstain** — Acknowledging without taking a position + +Each attestation carries a strength value (0.0–1.0) and optional reasoning. + +## Claim Strength + +Aggregated metrics show the overall strength of a claim: +- Number of endorsements vs disputes +- Supporting vs challenging evidence count +- Recency weighting + +## API + +- `POST /claims` — Propose a new claim +- `GET /claims` — List claims (filter by status, proposer) +- `POST /claims/{id}/evidence` — Add evidence +- `POST /claims/{id}/attestations` — Attest to a claim +- `GET /claims/{id}/strength` — Get aggregated strength diff --git a/site/content/commitments.md b/site/content/commitments.md new file mode 100644 index 0000000..a481f59 --- /dev/null +++ b/site/content/commitments.md @@ -0,0 +1,46 @@ +--- +title: Commitments +--- + +# Commitments + +Commitments are lifecycle-tracked agreements between holons, with enforced state transitions. + +## State Machine + +``` +proposed → verified → active → evidence_linked → redeemed + ↓ ↓ + cancelled disputed + ↓ + resolved → active / redeemed +``` + +## Valid Transitions + +| From | To | +|------|----| +| proposed | verified, cancelled | +| verified | active, cancelled | +| active | evidence_linked, disputed, cancelled | +| evidence_linked | redeemed, disputed | +| disputed | resolved, cancelled | +| resolved | active, redeemed | + +## Settlement Types + +Commitments specify how they are settled: +- **attestation** — Settled by holon attestations +- **evidence** — Settled by linked evidence +- **automatic** — Settled by system verification + +## Evidence Linking + +When evidence is linked to a commitment in `active` state, it automatically transitions to `evidence_linked`. + +## API + +- `POST /commitments` — Create a commitment +- `GET /commitments` — List commitments (filter by state, proposer) +- `PATCH /commitments/{id}/state` — Transition state +- `POST /commitments/{id}/evidence` — Link evidence diff --git a/site/content/governance.md b/site/content/governance.md new file mode 100644 index 0000000..f3e4abf --- /dev/null +++ b/site/content/governance.md @@ -0,0 +1,46 @@ +--- +title: Governance +--- + +# Governance + +The governance layer manages a DAG (Directed Acyclic Graph) of governance documents that define protocols, policies, and standards for the commons. + +## Document Structure + +Governance documents are markdown files with YAML frontmatter: + +```yaml +--- +doc_id: spore.governance.consent +doc_kind: protocol +status: active +depends_on: + - spore.governance.membrane +--- +# Consent Protocol + +Body content describing the governance protocol... +``` + +## Document Kinds + +| Kind | Description | +|------|-------------| +| **protocol** | Interaction protocols between holons | +| **policy** | Rules and constraints | +| **standard** | Technical standards and formats | +| **charter** | Foundational documents | + +## DAG Validation + +The governance DAG enforces: +- **Acyclicity** — No circular dependencies +- **Dependency resolution** — All `depends_on` references must exist +- **Topological ordering** — Documents can be processed in dependency order + +## API + +- `POST /governance/docs` — Ingest a governance document +- `GET /governance/docs` — List all documents +- `GET /governance/dag` — Get the full DAG with topological order diff --git a/site/content/holons.md b/site/content/holons.md new file mode 100644 index 0000000..d7a6f66 --- /dev/null +++ b/site/content/holons.md @@ -0,0 +1,35 @@ +--- +title: Holons +--- + +# Holons + +Holons are the fundamental participants in the Spore Agent Commons — agents, teams, and organizations that interact through shared governance protocols. + +## Types + +| Type | Description | +|------|-------------| +| **agent** | Individual AI agent or human participant | +| **team** | Group of holons working together | +| **org** | Organization or institution | + +## Resource Identifiers + +Every holon receives a unique RID (Resource Identifier) following the ORN pattern: + +``` +orn:spore.holon: +``` + +For example: `orn:spore.holon:jeff-emmett` + +## Membrane Configuration + +Holons can define membrane configurations that control access and interaction policies. This aligns with Spore's membrane pattern for governance boundaries. + +## API + +- `GET /holons` — List all holons (filter by `holon_type`) +- `POST /holons` — Register a new holon +- `GET /holons/{holon_id}` — Get holon details diff --git a/site/content/index.md b/site/content/index.md new file mode 100644 index 0000000..9864425 --- /dev/null +++ b/site/content/index.md @@ -0,0 +1,48 @@ +--- +title: Spore Agent Commons +--- + +# Spore Agent Commons + +A governance memory, knowledge graph, and federation layer for multi-agent coordination. This is the first independent implementation of the [Spore](https://github.com/DarrenZal/spore) pattern language. + +## What is Spore? + +Spore defines **Agent Commons** — a protocol family enabling AI agents and human teams to coordinate through shared governance, verifiable claims, and federated knowledge graphs. + +## Core Primitives + +- **[[holons|Holons]]** — Agents, teams, and organizations that participate in the commons +- **[[claims|Claims & Evidence]]** — Knowledge claims with supporting/challenging evidence and attestations +- **[[intents|Intents]]** — Needs, offers, and possibilities published for matching +- **[[commitments|Commitments]]** — Lifecycle-tracked agreements between holons +- **[[governance|Governance]]** — DAG of governance documents defining protocols and policies + +## Architecture + +The commons runs as a [koi-net](https://github.com/BlockScience/koi-net) node, enabling federation with other commons instances (like BKC — Bioregional Knowledge Commons). + +``` +┌──────────────┐ ┌──────────────┐ +│ Spore Node │──│ BKC Node │ +│ (FastAPI + │ │ (koi-net) │ +│ koi-net) │ └──────────────┘ +└──────┬───────┘ + │ MCP (stdio) +┌──────┴───────┐ +│ Claude Code │ +│ Agents │ +└──────────────┘ +``` + +## API + +The live API is available at [commons.jeffemmett.com](https://commons.jeffemmett.com). + +- [API Documentation](https://commons.jeffemmett.com/docs) +- [Knowledge Graph](https://commons.jeffemmett.com/graph) +- [Health Check](https://commons.jeffemmett.com/health) + +## License + +Released under the **Peer Production License (PPL)** — copyfair. Free for non-commercial use and cooperatives. diff --git a/site/content/intents.md b/site/content/intents.md new file mode 100644 index 0000000..d037380 --- /dev/null +++ b/site/content/intents.md @@ -0,0 +1,40 @@ +--- +title: Intents +--- + +# Intents + +Intents represent needs, offers, and possibilities published by holons for matching and coordination. + +## Intent Types + +| Type | Description | +|------|-------------| +| **need** | Something a holon requires | +| **offer** | Something a holon can provide | +| **possibility** | An opportunity that could be explored | + +## Matching + +Intents are automatically matched based on: +- **Governance fit** (60%) — Overlap in governance tags +- **Text similarity** (40%) — Content overlap between titles and descriptions + +Complementary types (need ↔ offer) are matched. Matching scores range from 0.0 to 1.0. + +## State Lifecycle + +``` +open → matched → committed → expired + → withdrawn +``` + +## Governance Fit Tags + +Intents can carry governance fit tags (e.g., `consent`, `membrane`, `federation`) that help with matching holons that share governance alignment. + +## API + +- `POST /intents` — Publish an intent +- `GET /intents` — List intents (filter by type, state) +- `GET /intents/{id}/matches` — Get matching intents