naive-framework 0.0.0-stage → 0.1.0

package/schema/integration.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "integration.schema.json",
+  "title": "Layer tooling integration",
+  "description": "One tool or service a layer can use. Each layer lists its integrations in <layer>/tooling/integrations.json. Credentials are named, never stored. Entries under interface/ are interfaces, not integrations: they must reach at least three of the five other layers (EE-038) (schema/check-integrations.mjs). Knowledge integrations with a connector are the connector registry (EE-037): a venture's knowledge/sources.json names them by id.",
+  "type": "object",
+  "required": [
+    "id",
+    "name",
+    "layer",
+    "role",
+    "interfaces",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string"
+    },
+    "layer": {
+      "enum": [
+        "purpose",
+        "knowledge",
+        "operations",
+        "evidence",
+        "governance",
+        "interface"
+      ]
+    },
+    "role": {
+      "type": "string",
+      "description": "What the layer uses it for, in a few words"
+    },
+    "interfaces": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "files",
+          "mcp",
+          "api",
+          "sdk",
+          "cli",
+          "webhook",
+          "app"
+        ]
+      },
+      "description": "How agents and code reach it"
+    },
+    "reach": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "purpose",
+          "knowledge",
+          "operations",
+          "evidence",
+          "governance"
+        ]
+      },
+      "description": "Interface layer only: the other layers a person can work in through it, in one session. At least three of the five."
+    },
+    "interface_kind": {
+      "enum": [
+        "agent-harness",
+        "custom"
+      ],
+      "description": "Interface layer only: an agent harness (built around an AI agent's loop, tools and files) or a custom interface built for the system or a venture."
+    },
+    "status": {
+      "enum": [
+        "in-use",
+        "candidate",
+        "rejected"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "description": "Why it is in use, a candidate, or rejected"
+    },
+    "credentials": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Environment variable names only"
+    },
+    "adapter": {
+      "type": "string",
+      "description": "Path to the skill, MCP config or script that wires it in, when one exists"
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "connector": {
+      "type": "object",
+      "required": [
+        "module",
+        "writes"
+      ],
+      "additionalProperties": false,
+      "description": "Knowledge layer only: the module that implements the connector contract (knowledge/connectors/contract.mjs) for this integration, so a venture's knowledge/sources.json can keep records in it (EE-037)",
+      "properties": {
+        "module": {
+          "type": "string",
+          "pattern": "^(knowledge|platform)/connectors/[a-z0-9-]+\\.mjs$",
+          "description": "Path from the repository root; it exports connect(options). A connector that works offline and names no vendor is framework (knowledge/connectors/); any other is platform (platform/connectors/), EE-041"
+        },
+        "writes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "direct",
+              "pull-request",
+              "none"
+            ]
+          },
+          "description": "The write modes it supports; the first is its default"
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The source options it takes, besides id and writes"
+        },
+        "eval": {
+          "type": "string",
+          "description": "The command that runs the contract evals against it"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/knowledge-sources.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "knowledge-sources.schema.json",
+  "title": "Knowledge sources",
+  "description": "A venture's source map (<venture>/knowledge/sources.json, EE-037): the sources its records live in and which record types live where. Optional: a record type it does not name, and every record of a venture without one, lives in the venture's own folder (the implicit `venture` source). The venture decides its own layout; Mentura does not. Rules make it a source-of-truth matrix: a system of record per record type, attribute and context, written for a fast model to read (EE-042). Each source names a connector from the registry (an integration with a `connector` in knowledge/tooling/integrations.json). Credentials are named by environment variable, never stored.",
+  "type": "object",
+  "required": ["sources", "records"],
+  "additionalProperties": false,
+  "properties": {
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "connector"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "not": { "const": "venture" }, "description": "The source's id; `venture` is reserved for the venture's own folder" },
+          "connector": { "type": "string", "description": "An integration id with a connector: filesystem, github" },
+          "writes": { "enum": ["direct", "pull-request", "none"], "description": "How writes reach it; the connector's default when left out" },
+          "root": { "type": "string", "description": "filesystem: the folder, relative to the venture folder or absolute. github: the folder inside the repository" },
+          "repo": { "type": "string", "pattern": "^[\\w.-]+/[\\w.-]+$", "description": "github: owner/name" },
+          "ref": { "type": "string", "description": "github: the branch (default main)" },
+          "token": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "github: the environment variable holding a token (default GITHUB_TOKEN)" },
+          "api": { "type": "string", "description": "github: the API base, for GitHub Enterprise" },
+          "search": { "enum": ["api", "scan"], "description": "github: code search (default) or a scan of the files" },
+          "note": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "records": {
+      "type": "object",
+      "description": "Record type id (from schema/data-model.json) -> source id. Unnamed record types stay in the venture folder.",
+      "additionalProperties": { "type": "string" }
+    },
+    "rules": {
+      "type": "array",
+      "description": "The source-of-truth matrix (EE-042). Each rule is one cell: for one record type in one context, its system of record and owner. Every field is present and \"*\" means any, so a fast model reads a rule without inferring anything. The rule with the most fields that are not \"*\" wins; two that tie fail the check. `records` is shorthand for rules that match anything.",
+      "items": {
+        "type": "object",
+        "required": [
+          "record",
+          "attribute",
+          "phase",
+          "product",
+          "account",
+          "actor",
+          "system_of_record",
+          "owner"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record": {
+            "type": "string",
+            "description": "A venture record type id from schema/data-model.json"
+          },
+          "attribute": {
+            "type": "string",
+            "pattern": "^(\\*|[a-z_][a-z0-9_]*)$",
+            "description": "\"*\" for the whole record, or one top-level field mastered elsewhere (such as price). The router reads the field from that source and writes it there, kept at the record's own path as a JSON object holding only that field; the record's own file does not keep a copy."
+          },
+          "phase": {
+            "enum": [
+              "*",
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ],
+            "description": "The venture's phase this rule holds in"
+          },
+          "product": {
+            "type": "string",
+            "pattern": "^(\\*|[a-z0-9][a-z0-9-]*)$",
+            "description": "A product id, or \"*\""
+          },
+          "account": {
+            "type": "string",
+            "pattern": "^(\\*|[a-z0-9][a-z0-9-]*)$",
+            "description": "An account id, or \"*\""
+          },
+          "actor": {
+            "enum": [
+              "*",
+              "person",
+              "agent"
+            ],
+            "description": "Who is reading or writing"
+          },
+          "system_of_record": {
+            "type": "string",
+            "description": "A source id from `sources`, or venture for the venture's own folder"
+          },
+          "owner": {
+            "type": "string",
+            "description": "The role accountable for this cell's data (the MDM data owner), a role id from governance decision rights or the team plan"
+          },
+          "survivorship": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "also_in",
+              "winner"
+            ],
+            "description": "When the same record also lives in other sources, which value wins. Running these rules across vendors is the platform's; the framework only states and checks them.",
+            "properties": {
+              "also_in": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1
+              },
+              "winner": {
+                "enum": [
+                  "system-of-record",
+                  "most-recent"
+                ]
+              }
+            }
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "note": { "type": "string" }
+  }
+}

package/schema/layer.json

@@ -0,0 +1,46 @@
+{
+  "layer": "system",
+  "purpose": "Hold the records every layer shares (workspace, venture, nouns, references, tooling, the data model and layer manifests, the provenance log) and the checks that tie the layers together.",
+  "product": "everything-ecosystem/kit",
+  "skills": [],
+  "records": [
+    "workspace",
+    "venture",
+    "ontology",
+    "reference",
+    "integration",
+    "business-models",
+    "scaffold",
+    "data-model",
+    "kit-manifest",
+    "need-now",
+    "provenance",
+    "venture-packages",
+    "venture-package"
+  ],
+  "reads": [
+    "product",
+    "account",
+    "decision"
+  ],
+  "writes": [],
+  "checks": [
+    "test.mjs",
+    "schema/validate.py",
+    "schema/check-data-model.mjs",
+    "schema/check-ventures.mjs",
+    "schema/check-nouns.mjs",
+    "schema/check-integrations.mjs",
+    "schema/init-venture.mjs",
+    "schema/test.mjs",
+    "schema/need-now.mjs",
+    "schema/time-to-ready.mjs",
+    "schema/check-provenance.mjs",
+    "schema/packages.mjs",
+    "schema/packages-test.mjs",
+    "schema/decision-analytics.mjs",
+    "schema/decision-analytics-test.mjs"
+  ],
+  "gaps": [],
+  "name": "system"
+}

package/schema/layer.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "layer.schema.json",
+  "title": "Layer manifest",
+  "description": "What one layer of the framework repository holds, at <layer>/layer.json and schema/layer.json for the system layer (EE-018, EE-071). A layer organizes the framework repo. It is not a venture package. Venture packages live at packages/<name>/package.json. A kit is Mentura's word, at platform/kits/. schema/check-data-model.mjs checks this file.",
+  "type": "object",
+  "required": [
+    "name",
+    "layer",
+    "purpose",
+    "skills",
+    "records",
+    "reads",
+    "writes",
+    "checks"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "layer": {
+      "enum": [
+        "system",
+        "purpose",
+        "knowledge",
+        "operations",
+        "evidence",
+        "governance",
+        "interface"
+      ]
+    },
+    "purpose": {
+      "type": "string",
+      "description": "What the layer is for, in one sentence"
+    },
+    "product": {
+      "type": "string",
+      "description": "The product card that offers this layer's work, as <venture id>/<product id>"
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "path"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string",
+            "description": "The SKILL.md, from the repo root"
+          },
+          "tier": {
+            "enum": [
+              "governance",
+              "delivery",
+              "software-engineering",
+              "automation"
+            ],
+            "description": "Optional: the MAD tier a skill serves, for a venture that uses MAD (a separate product since EE-038)"
+          },
+          "standalone": {
+            "type": "boolean",
+            "description": "Useful without the rest of the layer"
+          },
+          "move_to": {
+            "type": "string",
+            "description": "A proposed owning layer or package, when the skill is filed in the wrong place"
+          },
+          "why": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "records": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Record types this layer owns (data-model ids). Venture records that a package owns are listed on the package, not here."
+    },
+    "reads": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Record types owned elsewhere that this layer's skills and checks read"
+    },
+    "writes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Record types owned elsewhere that this layer's skills write"
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Scripts that check or run this layer's records, from the repo root"
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Known missing parts"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "description": "The layer's name"
+    }
+  }
+}

package/schema/load-packages.mjs

@@ -0,0 +1,26 @@
+// Loads the venture package catalog (EE-071). Each package is packages/<name>/package.json.
+// packages/catalog.json holds the shared fit rules, the record dependency graph and the question
+// matrix. schema/packages.json is the alias stub for one release; loaders do not read it.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const CORE = ["title", "department", "departments", "purpose", "required", "optional", "refs", "planned", "base", "when", "why", "unlocks", "not_modeled"];
+const HANDOFF = ["title", "for", "from", "base", "when", "why", "unlocks", "not_modeled"];
+
+/** The catalog in the shape schema/packages.mjs and the idea routes expect. */
+export function loadPackages(repo) {
+  const catalog = JSON.parse(readFileSync(join(repo, "packages/catalog.json"), "utf8"));
+  const { order, note_split, ...rest } = catalog;
+  const take = (names, fields) => Object.fromEntries(names.map((n) => {
+    const p = join(repo, "packages", n, "package.json");
+    if (!existsSync(p)) throw new Error(`missing packages/${n}/package.json`);
+    const pkg = JSON.parse(readFileSync(p, "utf8"));
+    const o = {};
+    for (const k of fields) if (pkg[k] !== undefined) o[k] = pkg[k];
+    if (o.department && !o.function) o.function = o.department;
+    if (o.function && !o.department) o.department = o.function;
+    return [n, o];
+  }));
+  return { ...rest, core: take(order.core, CORE), handoff: take(order.handoff, HANDOFF) };
+}