structured-context 0.12.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

@@ -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

@@ -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/generated/0.13.0/_structured_context_schema_meta.json

@@ -0,0 +1,400 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/0.13.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
+              },
+              "expression": {
+                "type": "string",
+                "minLength": 1
+              },
+              "when": {
+                "type": "string",
+                "minLength": 1
+              },
+              "semantic": {
+                "oneOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "rubric": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "verdicts": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "oneOf": [
+                            {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "description": {
+                                  "type": "string",
+                                  "minLength": 1
+                                },
+                                "guidance": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "required": ["description"],
+                              "additionalProperties": false
+                            }
+                          ]
+                        },
+                        "minProperties": 2
+                      },
+                      "severity": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "enum": ["error", "warning", "info", "ignore"]
+                        },
+                        "minProperties": 1
+                      },
+                      "scope": {
+                        "type": "array",
+                        "items": {
+                          "enum": ["parent", "siblings", "children", "ancestors", "descendants", "branch"]
+                        },
+                        "uniqueItems": true
+                      },
+                      "includeContent": {
+                        "enum": ["nodeOnly", "fullScope", true]
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                ]
+              },
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "global": {
+                "type": "boolean"
+              },
+              "override": {
+                "type": "boolean"
+              },
+              "gatesDescendants": {
+                "type": "boolean"
+              }
+            },
+            "required": ["id", "category", "description"],
+            "additionalProperties": false,
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "required": ["expression"]
+                  },
+                  {
+                    "required": ["semantic"]
+                  }
+                ]
+              },
+              {
+                "if": {
+                  "required": ["global"],
+                  "properties": {
+                    "global": {
+                      "const": true
+                    }
+                  }
+                },
+                "then": {
+                  "not": {
+                    "anyOf": [
+                      {
+                        "required": ["when"]
+                      },
+                      {
+                        "required": ["type"]
+                      },
+                      {
+                        "required": ["semantic"]
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["verdicts"]
+                    }
+                  }
+                },
+                "then": {
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["severity"]
+                    }
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "not": {
+                        "required": ["verdicts"]
+                      }
+                    }
+                  }
+                },
+                "then": {
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "properties": {
+                        "severity": {
+                          "type": "object",
+                          "not": {
+                            "required": ["fail"]
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["verdicts"]
+                    }
+                  },
+                  "not": {
+                    "required": ["expression"]
+                  }
+                },
+                "then": {
+                  "not": {
+                    "required": ["severity"]
+                  }
+                }
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}