sysprom 1.18.0 → 1.19.0

package/README.md

@@ -82,7 +82,7 @@ sysprom query node D1
 sysprom query rels --from D1
 sysprom query trace I1
 sysprom query timeline
-sysprom query state-at 2026-03-22
+sysprom query state-at <ISO-timestamp>
 
 # Add nodes (ID auto-generated from type prefix if --id omitted)
 
@@ -116,7 +116,7 @@ All commands auto-detect the document — they search the current directory for
 
 ## MCP Server
 
-SysProM includes an MCP (Model Context Protocol) server exposing 15 tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.
+SysProM includes an MCP (Model Context Protocol) server exposing tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.
 
 ### Configuration
 
@@ -245,6 +245,47 @@ if (node.is(thing)) {
 
 SysProM models systems as directed graphs across abstraction layers — intent, concept, capability, structure, and realisation — with explicit decisions, changes, and invariants. It is domain-agnostic, format-agnostic, and recursively composable.
 
+## System Provenance Profile
+
+For product repositories, use SysProM to model the specification, design, and implementation of the system being built.
+
+Recommended node usage:
+
+- `intent`: user outcomes, business goals, and product promises
+- `concept`: domain concepts, behavioural boundaries, and system rules
+- `capability`: user-visible or externally meaningful system behaviours
+- `element`: architectural components, services, stores, queues, and UI surfaces
+- `realisation`: implementation units such as packages, modules, handlers, schemas, and jobs
+- `protocol`: workflows and lifecycle paths such as review, publish, sync, or ingestion flows
+- `artefact`: API contracts, documents, prompts, tests, migrations, and generated outputs
+- `decision`: selected trade-offs and architectural choices
+- `change`: implementation slices or delivery units
+- `role`: human or system actors
+- `view`: curated slices such as specification, architecture, implementation, and operations
+
+Recommended trace chain:
+
+```text
+intent -> concept -> capability -> element -> realisation -> artefact
+```
+
+Recommended relationship usage:
+
+- `refines`: tighten intent into concepts and concepts into capabilities
+- `part_of`: decompose concepts, protocols, capabilities, and architecture structures
+- `realises`: connect design structures to implementation structures
+- `produces`: connect capabilities or stages to the artefacts they generate
+- `performs`: connect roles to capabilities, stages, protocols, and operational concepts
+- `governed_by` / `constrained_by`: express rules, policies, and invariants on design and implementation
+- `implements` / `modifies`: connect delivery changes to the nodes they implement or alter
+- `affects` + `must_preserve`: connect decisions to impacted areas and their protected invariants
+
+Recommended implementation provenance:
+
+- use `external_references` on `realisation` nodes to point to code paths, packages, handlers, or schemas
+- use `external_references` on `artefact` nodes to point to API definitions, test files, migrations, docs, PRs, and generated outputs
+- use `status`, `scope`, and decision/change links so the graph can answer both “what is the design?” and “what has actually been built?”
+
 ## How SysProM Compares
 
 <table>
@@ -363,7 +404,7 @@ sysprom md2json --input ./.SysProM --output .SysProM.json
 
 ## Claude Code Plugin
 
-SysProM is available as a Claude Code plugin with 28 skills for managing provenance documents. The plugin is defined in `.claude-plugin/marketplace.json` with skills in `.claude/skills/`.
+SysProM is available as a Claude Code plugin with skills for managing provenance documents. The plugin is defined in `.claude-plugin/marketplace.json` with skills in `.claude/skills/`.
 
 ### Install from Marketplace
 
@@ -383,25 +424,25 @@ When working on the SysProM repo itself, skills in `.claude/skills/` are auto-di
 
 ### Skills by Category
 
-**Node Creation (4 skills)**
+**Node Creation**
 
 - `add-decision` — Create decision nodes with context, options, rationale, and invariant links
 - `add-change` — Create change nodes with scope, operations, and task tracking
 - `add-invariant` — Create invariant nodes representing system rules and constraints
 - `add-node` — Generic node creation for any SysProM type
 
-**Node Modification (3 skills)**
+**Node Modification**
 
 - `update-node` — Modify node fields, status, lifecycle, context, or rationale
 - `remove-node` — Delete nodes with safety flags (hard delete, recursive, repair)
 - `rename-node` — Rename node IDs across all references
 
-**Relationships (2 skills)**
+**Relationships**
 
 - `add-relationship` — Create relationships between nodes with specific types
 - `remove-relationship` — Delete relationships
 
-**Query & Analysis (5 skills)**
+**Query & Analysis**
 
 - `query-nodes` — Search nodes by type, status, text, or ID
 - `query-relationships` — Query relationships by source, target, or type
@@ -409,31 +450,31 @@ When working on the SysProM repo itself, skills in `.claude/skills/` are auto-di
 - `check-document` — Validate document structure and report issues
 - `stats` — Show document statistics and composition metrics
 
-**Visualisation (1 skill)**
+**Visualisation**
 
 - `graph` — Generate Mermaid or DOT graphs with filtering
 
-**Format Conversion (4 skills)**
+**Format Conversion**
 
 - `init-document` — Create new SysProM documents with metadata
 - `json-to-markdown` — Convert JSON to Markdown format
 - `markdown-to-json` — Convert Markdown to JSON format
 - `sync-formats` — Bidirectional sync between JSON and Markdown
 
-**Spec-Kit Integration (4 skills)**
+**Spec-Kit Integration**
 
 - `speckit-import` — Import Spec-Kit features as SysProM nodes
 - `speckit-export` — Export SysProM nodes to Spec-Kit format
 - `speckit-sync` — Bidirectional sync with Spec-Kit specifications
 - `speckit-diff` — Show differences between SysProM and Spec-Kit
 
-**Task Management (3 skills)**
+**Task Management**
 
 - `task-list` — List tasks in a change node with progress
 - `task-add` — Add tasks to a change
 - `task-mark-done` — Mark tasks as complete
 
-**Plan Management (2 skills)**
+**Plan Management**
 
 - `plan-init` — Initialise plans with phases and gates
 - `plan-status` — Show plan progress and phase gates

package/dist/src/endpoint-types.js

@@ -161,7 +161,14 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
     // Performs — process enactment
     performs: {
         from: ["stage", "role"],
-        to: ["capability", "artefact", "artefact_flow", "stage"],
+        to: [
+            "capability",
+            "artefact",
+            "artefact_flow",
+            "stage",
+            "concept",
+            "protocol",
+        ],
     },
     // Precedes — temporal ordering
     precedes: {
@@ -185,6 +192,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
             "stage",
             "policy",
             "principle",
+            "protocol",
             "role",
             "gate",
             "mode",
@@ -260,7 +268,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
     },
     // Applies to — applicability and scope
     applies_to: {
-        from: ["policy", "principle", "mode", "protocol"],
+        from: ["policy", "principle", "mode", "protocol", "invariant"],
         to: [
             "intent",
             "concept",
@@ -275,7 +283,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
     },
     // Produces — generation
     produces: {
-        from: ["stage", "artefact_flow", "realisation", "concept"],
+        from: ["stage", "artefact_flow", "realisation", "concept", "capability"],
         to: ["artefact", "concept"],
     },
     // Consumes — usage

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sysprom",
-	"version": "1.18.0",
+	"version": "1.19.0",
 	"description": "SysProM — System Provenance Model CLI and library",
 	"author": "ExaDev",
 	"homepage": "https://exadev.github.io/SysProM",