# GraphSpec v0.10.0 Overview

GraphSpec, the Graph Speccing Framework, is a graph-based data model for software specifications, optimizing primarily for "AI agent comprehension" and "AI agent updates." Core architecture centers on three fundamental elements: nodes (typed specifications), edges (attributed relations), and vocabularies (versioned type registries).

## Key Design Principles

GraphSpec prioritizes "AI agent comprehension" as its top design priority, followed by agent-friendly update mechanics. The spec deliberately keeps its core minimal—"18 node kinds, 9 edge kinds, 8 invariants"—relegating domain-specific extensions to separate vocabularies rather than expanding the base.

## Core Components

**Nodes** represent identifiable specifications (Decisions, Components, Schemas) sharing a uniform structure. Every node carries required fields including URI, kind, version, scope, and timestamps. Derived fields like `lifecycle` and `realization` compute from attestations rather than being directly authored.

**Edges** are typed relations with attributes like confidence and validity windows. Nine canonical edge kinds exist (`contains`, `depends-on`, `implements`, `traces-to`, `supersedes`, `references`, `extends`, `governs`, `evidence-for`), with extension vocabularies adding domain-specific relationships.

**Identity** uses stable URIs: `graphspec://<vocab>/<namespace>/<name>`. Notably, "kind is not part of the URI"—nodes can change type through supersession without identity shifts.

## Lifecycle & Realization

Two independent axes drive most queries:

- **Lifecycle**: `proposed → accepted → deprecated → retired → tombstoned` (monotone forward)
- **Realization**: `none/planned/built/running/decommissioned/unknown` (non-monotone; operational state)

This split enables auditing the critical case: "code still alive after spec retirement."

## Governance Module

Optional Governance enables approval workflows, role-based access control, and cryptographically signed Attestations. Three canonical roles ship by default: Reader, Author, and Approver. Predicates define what each Attestation claims about a subject, using DSSE (Dead Simple Signing Envelope) for signatures.

## Query & Tooling

GraphSpec uses openCypher for graph queries and exposes canonical derived predicates (`lifecycle()`, `realization()`, `owners()`, `running()`, etc.) with identical semantics across implementations. The CLI provides `validate`, `query`, `resolve`, `index`, and `release` verbs. An MCP server integrates with AI clients via discoverable tools.

Human and agent actors are "first-class peers"—all Principals (distinguished by type: human, agent, group, service-account) can perform authorized actions uniformly.