naive-framework 0.0.0-stage → 0.2.0

package/schema/knowledge-sources.schema.json

@@ -0,0 +1,260 @@
+{
+  "$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. Beside the sources Naive reads records from, `functions` says where each of the venture's functions keeps its truth outside Naive (EE-083): the repo, hosting and analytics for the product, a payments or store account for sales, the bank for money, a folder or signing service for legal documents. Those are pointers to systems of record; a system Naive reads through code is connected, one it only knows of is pointed. `truth` says where the venture's source of truth as a whole lives.",
+  "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"
+    },
+    "truth": {
+      "type": "string",
+      "description": "local: this device is the source of truth; otherwise the address of the host every system is backed up to or hosted on (EE-083)"
+    },
+    "functions": {
+      "type": "object",
+      "description": "Each function's systems of record, by department id (operations/departments.json) or legal (EE-083)",
+      "propertyNames": {
+        "enum": [
+          "strategy",
+          "products",
+          "marketing-and-sales",
+          "supply-chain",
+          "service-delivery",
+          "customer-service",
+          "human-capital",
+          "it",
+          "finance",
+          "assets",
+          "risk-and-compliance",
+          "external-relationships",
+          "capabilities",
+          "legal"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "systems"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "systems": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "system",
+                "status"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "system": {
+                  "type": "string",
+                  "description": "A system id from schema/systems-catalog.json"
+                },
+                "address": {
+                  "type": "string"
+                },
+                "source": {
+                  "type": "string",
+                  "description": "The source in `sources` that reads it, when it is one"
+                },
+                "status": {
+                  "enum": [
+                    "connected",
+                    "pointed"
+                  ],
+                  "description": "connected: read by code (a connector or an integration); pointed: known, not read yet"
+                },
+                "synced": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "fixture": {
+                  "type": "boolean",
+                  "description": "The last sync replayed a saved answer, not the live system"
+                }
+              }
+            }
+          },
+          "note": {
+            "type": "string",
+            "description": "What the founder said about this function, in their words"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/layer.json

@@ -0,0 +1,59 @@
+{
+  "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",
+    "release",
+    "naive-config",
+    "venture-types",
+    "frame",
+    "upgrade-registry",
+    "kit"
+  ],
+  "reads": [
+    "product",
+    "account",
+    "decision",
+    "team-plan"
+  ],
+  "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",
+    "schema/check-config.mjs",
+    "schema/gate-test.mjs",
+    "schema/upgrades.mjs",
+    "schema/upgrades-test.mjs",
+    "schema/triggers.mjs",
+    "schema/stale.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) };
+}

package/schema/marketing-brand.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "marketing-brand.schema.json",
+  "title": "Brand",
+  "description": "The venture's brand tokens, in the marketing package at marketing/brand.json: colors, typefaces with their licenses, the font each role uses, voice rules (the global stylesheet for words), the logo and marks, outside design systems by reference, and scopes where a route prefix overrides the venture brand (nearer context wins). Read by every agent's layout and every interface; checked by schema/check-brand.mjs. Translates Next.js global CSS, next/font and file-based icons (Y-3, Y-4, Y-5, T-1, T-2, P-24). Version 0.x, unevaluated.",
+  "type": "object",
+  "required": ["version", "venture"],
+  "additionalProperties": false,
+  "$defs": {
+    "colors": {
+      "type": "object",
+      "description": "Token name -> hex color",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }
+    },
+    "fonts": {
+      "type": "object",
+      "description": "Role (body, heading, mono, display...) -> typeface id",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "type": "string" }
+    },
+    "rule": {
+      "type": "object",
+      "required": ["id", "avoid"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "avoid": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }], "description": "A phrase, or phrases, the venture's words never use; matched as whole words, ignoring case" },
+        "use": { "type": "string", "description": "What to write instead" },
+        "why": { "type": "string" }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tone": { "type": "array", "items": { "type": "string" }, "description": "How the venture sounds, in a few words each" },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" } }
+      }
+    }
+  },
+  "properties": {
+    "version": { "type": "string" },
+    "venture": { "type": "string" },
+    "name": { "type": "string", "description": "The name as the brand writes it" },
+    "colors": { "$ref": "#/$defs/colors" },
+    "typefaces": {
+      "type": "array",
+      "description": "Each typeface, defined once with its license (T-1). self-hosted: its files are in public/ and registered, so a browser makes no outside request; system: the reader's own fonts; remote: served from another host (the check fails it)",
+      "items": {
+        "type": "object",
+        "required": ["id", "family", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "family": { "type": "string" },
+          "source": { "enum": ["self-hosted", "system", "remote"] },
+          "license": { "type": "string", "description": "An SPDX id such as OFL-1.1, or owned, or licensed" },
+          "files": { "type": "array", "items": { "type": "string", "pattern": "^public/" } },
+          "url": { "type": "string" },
+          "fallback": { "type": "array", "items": { "type": "string" } },
+          "credit": { "type": "string" }
+        }
+      }
+    },
+    "fonts": { "$ref": "#/$defs/fonts", "description": "The font each role uses everywhere, as the root layout applies it (T-2)" },
+    "voice": { "$ref": "#/$defs/voice" },
+    "marks": {
+      "type": "array",
+      "description": "The logo and marks (P-24), each a registered file in public/",
+      "items": {
+        "type": "object",
+        "required": ["kind", "asset"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "enum": ["logo", "icon", "apple-icon", "favicon"] },
+          "asset": { "type": "string", "pattern": "^public/" },
+          "use": { "type": "string" }
+        }
+      }
+    },
+    "design_systems": {
+      "type": "array",
+      "description": "Outside design systems the brand builds on, by reference: linked, with a version and license, never copied in (Y-4)",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "url", "license"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "name": { "type": "string" },
+          "url": { "type": "string" },
+          "version": { "type": "string" },
+          "license": { "type": "string" },
+          "uses": { "type": "array", "items": { "type": "string" }, "description": "What the venture takes from it" }
+        }
+      }
+    },
+    "scopes": {
+      "type": "array",
+      "description": "Overrides for a route prefix (a package such as investors, or one item such as investors/deck). Nearer context wins: a deeper prefix over a shallower one, any scope over the venture brand (Y-5, T-2)",
+      "items": {
+        "type": "object",
+        "required": ["for"],
+        "additionalProperties": false,
+        "properties": {
+          "for": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$" },
+          "colors": { "$ref": "#/$defs/colors" },
+          "fonts": { "$ref": "#/$defs/fonts" },
+          "voice": { "$ref": "#/$defs/voice" },
+          "note": { "type": "string" }
+        }
+      }
+    }
+  }
+}