structured-context 0.11.0 → 0.13.0

package/schemas/_okf.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_okf",
+  // Open Knowledge Format v0.2 frontmatter families: core, provenance, trust, lifecycle, attested computation.
+  // OKF §4.1: consumers MUST NOT reject unknown fields, so every object here allows additional properties.
+  // Concept types are not registered centrally (§4.1), so there is deliberately no oneOf over `type` consts:
+  // type checking would reject every type not listed. `Attested Computation` is handled with if/then instead.
+  // index.md and log.md are reserved bundle files without a `type`; they are reported as excluded during parsing.
+  "$metadata": {
+    "rules": [
+      {
+        "id": "okf-description",
+        "category": "best-practice",
+        "severity": "warning",
+        "description": "Concepts should have a one-line description (used by index generators and search snippets)",
+        "expression": "$exists(current.description) and $length(current.description) > 0"
+      },
+      {
+        "id": "okf-stale-after-generated",
+        "category": "validation",
+        "description": "stale_after must be later than generated.at",
+        "expression": "$not($exists(current.stale_after)) or $not($exists(current.generated.at)) or $toMillis(current.stale_after) > $toMillis(current.generated.at)"
+      },
+      {
+        "id": "okf-usage-count-window",
+        "category": "coherence",
+        "severity": "warning",
+        "description": "A source's usage_count is only meaningful within a usage_window (on the source or shared at the top level)",
+        "expression": "$not($exists(current.sources)) or $count(current.sources[$exists(usage_count) and $not($exists(usage_window)) and $not($exists($$.current.usage_window))]) = 0"
+      },
+      {
+        "id": "okf-computation-present",
+        "category": "validation",
+        "type": "Attested Computation",
+        "description": "An Attested Computation needs its computation: a `computation` path or a body `# Computation` section. Known limitation: the section is found by matching a `# Computation` line in the body text, so such a line inside a code fence also counts",
+        "expression": "$exists(current.computation) or $contains(current.content, /^# Computation[ \\t]*$/m)"
+      }
+    ]
+  },
+  "$defs": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime with an explicit UTC offset, e.g. 2026-06-30T14:00:00Z (§5)"
+    },
+    "actor": {
+      "type": "string",
+      "minLength": 1,
+      "description": "<producer>/<version> for agents, human:<id> for people, process:<id> for automated processes (§7)"
+    },
+    "usageWindow": {
+      "type": "object",
+      "properties": {
+        "from": { "$ref": "#/$defs/timestamp" },
+        "to": { "$ref": "#/$defs/timestamp" }
+      },
+      "required": ["from", "to"]
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "resource": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Followable artifact (URL or path) or a scope descriptor"
+        },
+        "id": { "type": "string", "description": "Stable key for footnote attribution" },
+        "title": { "type": "string" },
+        "author": { "$ref": "#/$defs/actor" },
+        "usage_count": { "type": "integer", "minimum": 0 },
+        "last_modified": { "$ref": "#/$defs/timestamp" },
+        "usage_window": { "$ref": "#/$defs/usageWindow" }
+      },
+      "required": ["resource"]
+    },
+    "generated": {
+      "type": "object",
+      "properties": {
+        "by": { "$ref": "#/$defs/actor" },
+        "at": { "$ref": "#/$defs/timestamp" }
+      },
+      "required": ["by"]
+    },
+    "verification": {
+      "type": "object",
+      "properties": {
+        "by": { "$ref": "#/$defs/actor" },
+        "at": { "$ref": "#/$defs/timestamp" }
+      },
+      "required": ["by", "at"]
+    },
+    "okfProps": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Kind of concept; unregistered and open-ended (§4.1)"
+        },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "resource": { "type": "string", "minLength": 1, "description": "URI or path of the underlying asset" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
+        "usage_window": { "$ref": "#/$defs/usageWindow" },
+        "generated": { "$ref": "#/$defs/generated" },
+        "verified": {
+          "description": "One verification event, or a list of them (§5.2: a bare mapping is a one-element list)",
+          "anyOf": [
+            { "$ref": "#/$defs/verification" },
+            { "type": "array", "items": { "$ref": "#/$defs/verification" } }
+          ]
+        },
+        "status": { "type": "string", "enum": ["draft", "stable", "deprecated"], "default": "stable" },
+        "stale_after": { "$ref": "#/$defs/timestamp" }
+      },
+      "required": ["type"]
+    },
+    "concept": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "#/$defs/okfProps" },
+        {
+          "if": { "properties": { "type": { "const": "Attested Computation" } }, "required": ["type"] },
+          "then": { "$ref": "#/$defs/attestedComputation" }
+        }
+      ],
+      "additionalProperties": true
+    },
+    "attestedComputation": {
+      "type": "object",
+      "properties": {
+        "runtime": {
+          "type": "string",
+          "minLength": 1,
+          "description": "How to run the computation; defines what `parameters` mean (§10.2)"
+        },
+        "parameters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "type": { "type": "string", "minLength": 1 },
+              "required": { "type": "boolean" }
+            },
+            "required": ["name", "type"]
+          }
+        },
+        "computation": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to a file holding the computation, instead of the body fence"
+        },
+        "executor": {
+          "type": "object",
+          "properties": {
+            "resource": { "type": "string", "minLength": 1 },
+            "receipt": { "type": "array", "items": { "type": "string" }, "description": "Fields a run must return" }
+          },
+          "required": ["resource"]
+        },
+        "attester": {
+          "type": "object",
+          "properties": { "resource": { "type": "string", "minLength": 1 } },
+          "required": ["resource"]
+        }
+      },
+      "required": ["runtime"]
+    }
+  }
+}

package/schemas/_ost_strict.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://_ost_strict",
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_ost_strict",
   // Shared definitions for the strict OST (Opportunity Solution Tree) schema.
   // This schema follows Teresa Torres' canonical 4-level structure as described in
   // "Continuous Discovery Habits" (2021) and at producttalk.org.
@@ -13,28 +13,37 @@
         "id": "active-outcome-count",
         "category": "workflow",
         "description": "Only one outcome should be active at a time",
-        "scope": "global",
-        "check": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
+        "global": true,
+        "expression": "$count(nodes[resolvedType='outcome' and status='active']) <= 1"
       },
       {
         "id": "active-opportunity-count",
         "category": "workflow",
         "description": "Only one target opportunity should be active at a time",
-        "scope": "global",
-        "check": "$count(nodes[resolvedType='opportunity' and status='active']) <= 1"
+        "global": true,
+        "expression": "$count(nodes[resolvedType='opportunity' and status='active']) <= 1"
       },
       {
         "id": "active-node-parent-active",
         "category": "workflow",
         "description": "An active node's parent should also be active",
-        "check": "current.status != 'active' or $exists(parent) = false or parent.status = 'active'"
+        "expression": "current.status != 'active' or $exists(parent) = false or parent.status = 'active'"
       },
       {
         "id": "solution-quantity",
         "category": "best-practice",
         "description": "Explore multiple candidate solutions (aim for at least three) for the target opportunity",
         "type": "opportunity",
-        "check": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) >= 3"
+        "expression": "(current.status != 'exploring' and current.status != 'active') or $count(nodes[resolvedParentTitle=$$.current.title and resolvedType='solution']) >= 3"
+      },
+      {
+        "id": "opportunity-customer-voice",
+        "category": "best-practice",
+        "type": "opportunity",
+        "description": "Opportunity must be framed in the customer's voice (something a customer would actually say) as a need or pain point, not a solution or business goal",
+        "semantic": {
+          "rubric": "Verify that the opportunity is stated from the customer's perspective as a problem, pain point, or desire. It must not be a solution in disguise (e.g. 'build X feature') or a business metric (e.g. 'increase revenue')."
+        }
       }
     ]
   },

package/schemas/_sctx_base.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "sctx://_sctx_base",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sctx://core/_sctx_base",
   "description": "Shared definitions for structured-context schemas",
   "$defs": {
     "title": {
@@ -9,7 +9,7 @@
     },
     "content": {
       "type": "string",
-      "description": "Body content"
+      "description": "Markdown source of the node's body, excluding its own heading or list marker and any nested embedded nodes"
     },
     "summary": {
       "type": "string",

package/schemas/_strategy_general.json

@@ -1,9 +1,9 @@
 {
-  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://_strategy_general",
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_strategy_general",
   // Shared entity definitions for strategy-general schemas.
-  // Provides a default hierarchy, aliases, relationships, and entity type $defs.
-  // Composing schemas can override the hierarchy by defining their own.
+  // Provides a hierarchy, aliases, relationships, and entity type $defs.
+  // Schemas that import this partial get its metadata; a $ref to its $defs alone brings none.
   "$metadata": {
     "hierarchy": {
       "levels": [
@@ -45,7 +45,7 @@
   "$defs": {
     "dashboard": {
       "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "dashboard" }
       },
@@ -54,7 +54,7 @@
     },
     "ost_on_a_page": {
       "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
       },
@@ -64,8 +64,8 @@
     "vision": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "vision" }
@@ -83,9 +83,9 @@
     "mission": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "mission" }
@@ -103,13 +103,13 @@
     "goal": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "enum": ["goal", "outcome"] },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" }
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" }
       },
       "required": ["type"],
       "additionalProperties": true,
@@ -125,16 +125,16 @@
     "opportunity": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "opportunity" },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
-        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
         "timeline": {
           "type": "string",
           "description": "Timeline estimate (e.g., S-M, M-L)"
@@ -158,16 +158,16 @@
     "solution": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "solution" },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
-        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
         "timeline": {
           "type": "string",
           "description": "Timeline estimate (e.g., S-M, M-L)"
@@ -191,9 +191,9 @@
     "experiment": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "enum": ["experiment", "assumption_test", "test"] }
@@ -216,9 +216,9 @@
     "assumption": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "assumption" },
@@ -242,9 +242,9 @@
     "problem_statement": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "problem_statement" }

package/schemas/generated/0.12.0/_structured_context_schema_meta.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/0.12.0/_structured_context_schema_meta.json",
+  "title": "structured-context schema dialect",
+  "description": "Extends JSON Schema 2020-12 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "https://json-schema.org/draft/2020-12/schema"
+    }
+  ],
+  "properties": {
+    "$metadata": {
+      "type": "object",
+      "properties": {
+        "imports": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "hierarchy": {
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "override": {
+                  "type": "boolean"
+                },
+                "levels": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "oneOf": [
+                      {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "field": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "fieldOn": {
+                            "enum": ["child", "parent"]
+                          },
+                          "multiple": {
+                            "type": "boolean"
+                          },
+                          "templateFormat": {
+                            "enum": ["heading", "list", "table", "page"]
+                          },
+                          "matchers": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "minItems": 1
+                          },
+                          "embeddedTemplateFields": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
+                          "selfRef": {
+                            "type": "boolean"
+                          },
+                          "selfRefField": {
+                            "type": "string",
+                            "minLength": 1
+                          }
+                        },
+                        "required": ["type"],
+                        "additionalProperties": false
+                      }
+                    ]
+                  }
+                },
+                "allowSkipLevels": {
+                  "type": "boolean"
+                }
+              },
+              "required": ["levels"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "$ref": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": ["$ref"],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "relationships": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "parent": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "field": {
+                "type": "string",
+                "minLength": 1
+              },
+              "fieldOn": {
+                "enum": ["child", "parent"]
+              },
+              "multiple": {
+                "type": "boolean"
+              },
+              "templateFormat": {
+                "enum": ["heading", "list", "table", "page"]
+              },
+              "matchers": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1
+              },
+              "embeddedTemplateFields": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "override": {
+                "type": "boolean"
+              }
+            },
+            "required": ["parent", "type"],
+            "additionalProperties": false
+          }
+        },
+        "aliases": {
+          "type": "object",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "string",
+                "minLength": 1
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "override": {
+                    "type": "boolean"
+                  }
+                },
+                "required": ["type"],
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "category": {
+                "enum": ["validation", "coherence", "workflow", "best-practice"]
+              },
+              "severity": {
+                "enum": ["error", "warning", "info"]
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1
+              },
+              "check": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "scope": {
+                "enum": ["global"]
+              },
+              "override": {
+                "type": "boolean"
+              }
+            },
+            "required": ["id", "category", "description", "check"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}