SpillwaveSolutions · RichardHightower · Aug 13, 2026 · Aug 13, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
       "name": "okf-graph-eng",
       "source": "./",
       "description": "Graph engineering for OKF repos \u2014 impact analysis, agent/harness graphs, progressive disclosure, typed edges, TicketLink/worklog bridges. Works in Claude Code and Grok Build.",
-      "version": "0.4.1",
+      "version": "0.5.0",
       "author": {
         "name": "Rick Hightower"
       },

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "okf-graph-eng",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Graph engineering for OKF repos — impact analysis, agent/harness graphs, progressive disclosure, typed edges, TicketLink/worklog bridges, and curation. Works in Claude Code and Grok Build.",
   "author": {
     "name": "Rick Hightower",

diff --git a/.grok-plugin/marketplace.json b/.grok-plugin/marketplace.json
@@ -1,13 +1,13 @@
 {
   "name": "okf-plugin-marketplace",
   "description": "Optional native Grok marketplace metadata. Grok Build already loads Claude plugins with zero config; this file pins identity for Grok marketplace listings.",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "plugins": [
     {
       "name": "okf-graph-eng",
       "source": ".",
       "description": "OKF graph engineering — impact analysis, agent graphs, progressive disclosure. Claude-compatible.",
-      "version": "0.4.1",
+      "version": "0.5.0",
       "compatibility": {
         "claude_plugin": true,
         "zero_config": true

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,24 @@
 Notable changes to **okf-graph-eng**. Newest first. Released sections are
 frozen — corrections go in the next release's notes.
 
+## 0.5.0 — 2026-08-13
+
+### Added
+
+- **Shared concept schema pack** at `schemas/okf-concepts/`. Canonical
+  `BaseConcept` (required: `type` + `title` only; `additionalProperties: true`)
+  plus TicketLink, Feature, DecisionRecord, Project, Catalog, ContextPack.
+- `scripts/okf_schema.py` — stdlib subset validator. Soft by default. Merges
+  sibling plugin schema directories so a mixed second brain validates as one.
+- `okf-graph.py schemas` lists the merged registry.
+- `okf-graph.py validate` now runs schema checks (unknown types fall back to
+  BaseConcept as info; missing recommended fields are warnings).
+- `truth_state` union: `current | snapshot | superseded | archived | historical | proposed`.
+- TicketLink `kind=bug` refinement: warn unless the ticket links to a
+  Module/Package/Release/CodeChange or sets `branch`. Epic/story/task/bug
+  remain WikiTicket axes, not new concept types.
+- Catalog ownership map in `registry.json` so plugins do not rewrite foreign catalogs.
+
 ## 0.4.1 — 2026-08-10
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ Works in **Claude Code** and **Grok Build** (zero-config: Grok Build reads Claud
 |---|---|
 | **Plugin name** | `okf-graph-eng` |
 | **Repo** | [SpillwaveSolutions/okf-plugin](https://github.com/SpillwaveSolutions/okf-plugin) |
-| **Version** | 0.4.1 |
+| **Version** | 0.5.0 |
 | **License** | MIT |
 
 ## Why this plugin

diff --git a/marketplace.json b/marketplace.json
@@ -7,7 +7,7 @@
       "name": "okf-graph-eng",
       "source": "./",
       "description": "Graph engineering for OKF repos",
-      "version": "0.4.1"
+      "version": "0.5.0"
     }
   ]
 }
diff --git a/schemas/okf-concepts/BaseConcept.schema.json b/schemas/okf-concepts/BaseConcept.schema.json
@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/BaseConcept.schema.json",
+  "title": "OKF BaseConcept",
+  "description": "Shared frontmatter envelope for every OKF concept. Required fields stay at type + title forever on v1. extra properties are always allowed. truth_state accepts the union of PKC/SAC and DEKC vocabularies.",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Concept type. Unknown types fall back to this envelope."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "description": "Recommended, never required on v1."
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "ISO-8601. Recommended, never required on v1."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "status": {
+      "type": "string",
+      "description": "Free string. Domain plugins may recommend enums; unknown values warn, never error."
+    },
+    "verified": { "type": "boolean" },
+    "generated": { "type": "boolean" },
+    "wiki_key": { "type": "string" },
+    "truth_state": {
+      "type": "string",
+      "enum": [
+        "current",
+        "snapshot",
+        "superseded",
+        "archived",
+        "historical",
+        "proposed"
+      ],
+      "description": "Union of PKC/SAC (current|snapshot|superseded|archived) and DEKC (current|historical|proposed)."
+    },
+    "schema_version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Emitted on new writes. Never required on read."
+    },
+    "owner": { "type": "string" },
+    "owners": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "sources": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "stale_after": { "type": "string" },
+    "source_fingerprint": { "type": "string" },
+    "worklog_id": { "type": "string" },
+    "external_id": { "type": ["string", "number"] },
+    "external_system": { "type": "string" },
+    "cloud": { "type": "string" },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target"],
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Absolute in-bundle path, e.g. /features/checkout.md, or federation:<name>:/path"
+          },
+          "rel": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/Catalog.schema.json b/schemas/okf-concepts/Catalog.schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/Catalog.schema.json",
+  "title": "Catalog",
+  "description": "Index page for a catalog directory. Structural; usually skipped by concept walkers.",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": { "const": "Catalog" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/ContextPack.schema.json b/schemas/okf-concepts/ContextPack.schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/ContextPack.schema.json",
+  "title": "ContextPack",
+  "description": "Generated progressive-disclosure view. May freely include nodes from any plugin. Not a catalog-owned type.",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": { "const": "ContextPack" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "generated": { "type": "boolean" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target"],
+        "properties": {
+          "target": { "type": "string" },
+          "rel": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/DecisionRecord.schema.json b/schemas/okf-concepts/DecisionRecord.schema.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/DecisionRecord.schema.json",
+  "title": "DecisionRecord",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": { "const": "DecisionRecord" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string" },
+    "wiki_key": { "type": "string" },
+    "truth_state": { "type": "string" },
+    "verified": { "type": "boolean" },
+    "generated": { "type": "boolean" },
+    "schema_version": { "type": "integer" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target"],
+        "properties": {
+          "target": { "type": "string" },
+          "rel": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/Feature.schema.json b/schemas/okf-concepts/Feature.schema.json
@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/Feature.schema.json",
+  "title": "Feature",
+  "description": "Product capability. Materialized from WikiTicket epic/story items.",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": { "const": "Feature" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string" },
+    "priority": { "type": "string" },
+    "level": { "type": "string", "enum": ["epic", "story"] },
+    "kind": { "type": "string" },
+    "worklog_id": { "type": "string" },
+    "external_id": { "type": ["string", "number"] },
+    "external_system": { "type": "string" },
+    "wiki_key": { "type": "string" },
+    "truth_state": { "type": "string" },
+    "verified": { "type": "boolean" },
+    "generated": { "type": "boolean" },
+    "schema_version": { "type": "integer" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target"],
+        "properties": {
+          "target": { "type": "string" },
+          "rel": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/Project.schema.json b/schemas/okf-concepts/Project.schema.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spillwave.solutions/schemas/okf-concepts/Project.schema.json",
+  "title": "Project",
+  "description": "Top-level container for a multi-repo or federated second brain. Owns Features, Releases, and Packages.",
+  "type": "object",
+  "required": ["type", "title"],
+  "properties": {
+    "type": { "const": "Project" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string" },
+    "wiki_key": { "type": "string" },
+    "truth_state": { "type": "string" },
+    "verified": { "type": "boolean" },
+    "schema_version": { "type": "integer" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target"],
+        "properties": {
+          "target": { "type": "string" },
+          "rel": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/schemas/okf-concepts/README.md b/schemas/okf-concepts/README.md
@@ -0,0 +1,38 @@
+# Shared OKF concept schemas
+
+This is the **canonical envelope** for every plugin in the second-brain family
+(okf-plugin, PKC, SAC, DEKC, AGER).
+
+## Rules (load-bearing)
+
+1. Markdown body is always free-form. Only YAML frontmatter is schema-checked.
+2. **Required on v1: `type` + `title` only.** Never tighten without a major
+   `schema_version` and a migration.
+3. `additionalProperties: true` forever on BaseConcept.
+4. Soft validation is the default. Old files must produce **zero errors**.
+5. `truth_state` accepts the union of PKC/SAC and DEKC values:
+   `current | snapshot | superseded | archived | historical | proposed`.
+6. Unknown `type` values fall back to BaseConcept (info, not error).
+7. Epic / Story / Task / Subtask / Bug are **not** concept types. They live
+   as `level` / `kind` on `TicketLink` (and `level` on `Feature` for epic/story).
+8. Domain plugins add types under their own `schemas/okf-concepts/` and the
+   validator merges directories. Do not fork BaseConcept.
+
+## Catalog ownership
+
+A plugin may only rewrite catalogs listed under its name in `registry.json`
+`catalog_ownership`. Foreign catalogs are read-only.
+
+In a shared second brain:
+
+- `Module` lives in `modules/` (SAC convention).
+- `Package` lives in `packages/`.
+- Cross-plugin links are absolute in-bundle paths (`/tables/orders.md`).
+
+## Validate
+
+```bash
+python3 scripts/okf_schema.py list
+python3 scripts/okf-graph.py validate sample-okf
+python3 scripts/okf-graph.py validate sample-okf --schema
+```