naive-framework 0.0.0-stage → 0.2.0

package/schema/strategic-foundation.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "strategic-foundation.schema.json",
+  "title": "Strategic foundation frame",
+  "description": "The framework's map of strategic foundation (EE-051): per question of the Five Ws and How plus whether, the record attributes that answer it.",
+  "type": "object",
+  "required": [
+    "version",
+    "questions"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "ask",
+          "statements"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "ask": {
+            "type": "string"
+          },
+          "statements": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "record",
+                "attribute"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9-]+$"
+                },
+                "record": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "attribute": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "derived_from": {
+                  "type": "string",
+                  "description": "The id of another statement this one is derived from; it takes that statement's status and value"
+                },
+                "note": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/stream.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "stream.schema.json",
+  "title": "Data stream",
+  "description": "Declares one append-only stream under a data package's _streams/<id>/ (EE-070). sensitive true means the stream's events stay out of git and only summary.md is versioned.",
+  "type": "object",
+  "required": ["id", "sensitive"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "sensitive": { "type": "boolean" },
+    "summary": { "type": "string", "description": "What the versioned summary.md covers, when sensitive is true" }
+  }
+}

package/schema/structure.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// The venture folder's structure (Next.js translation P-3, P-22, P-32): what venture.json declares,
+// which folders are private, and which names Naive reserves.
+//
+//   node schema/structure.mjs <venture dir> [--json]      check the structure; exit 1 on an error
+//   node schema/structure.mjs manifest <venture dir>      print the manifest venture.json declares
+//
+// P-3 venture.json is Naive's package.json: identity, phase, governance, the function owners, and the
+//      packages and kits the venture uses (EE-071). packages and kits are declared the way
+//      package.json lists dependencies; when venture.json does not list packages, the manifest
+//      derives them (the core packages that fit the phase now, plus any package that holds records).
+// P-22 A folder whose name starts with _ is private: no route reaches a file under it unless the
+//      data model names that folder in a record's path (customers/_streams/*/stream.json). _drafts/
+//      holds writes waiting for a person, _private/ never reaches a model, _notes/ holds notes,
+//      _streams/ holds a data package's append-only activity.
+// P-32 Names reserved for Naive's own conventions, now and later. A venture that uses one for
+//      something else gets an error (the name already means something) or a warning (it will).
+//
+// Never calls a model. Reads the venture folder only.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+/** The private folders Naive knows, and what each holds (P-22). Any other _folder is private too. */
+export const PRIVATE = {
+  _drafts: "writes held for a person to accept; Naive writes it, at the venture root only",
+  _private: "never sent to a model and never released",
+  _notes: "the founder's working notes beside a package; never routed",
+  _streams: "a data package's append-only activity (customers, investors, money)",
+};
+
+/** Names reserved for Naive conventions (P-32). in_use: Naive gives them a meaning today; future: kept free for a convention to come. */
+export const RESERVED = {
+  in_use: {
+    "AGENTS.md": "a layout: instructions for agents in this folder and below",
+    "venture.json": "a venture's manifest; a folder holding one is a nested venture",
+    "naive.config.json": "the venture's overrides, at the venture root",
+    "provenance.jsonl": "the venture's provenance log, at the venture root",
+    _drafts: PRIVATE._drafts,
+    _streams: PRIVATE._streams,
+    ".release": "release plans and output",
+  },
+  future: {
+    "layout.md": "a folder's own layout file (L-5)",
+    "template.md": "context recomputed on every action (P-12)",
+    "error.md": "a package's own error answer (P-15)",
+    "loading.md": "a package's own pending state (P-37)",
+    "not-found.md": "a package's own missing-record answer (P-14)",
+    "default.md": "what a slot shows for a package with nothing in it (P-17)",
+    "page.md": "a record's people-facing page (P-10)",
+    ".naive": "generated framework files",
+  },
+  // Folder shapes that mean something to the router: (group) shares a layout (P-36); @slot and [param] are kept for later.
+  shapes: [
+    { re: /^\(.+\)$/, name: "(group)", rule: "a route group: it holds only its AGENTS.md, the layout its packages share (P-36)" },
+    { re: /^@.+/, name: "@slot", rule: "reserved for named slots (P-21)" },
+    { re: /^\[.+\]$/, name: "[param]", rule: "reserved for dynamic segments (P-19); collections are declared by the data model, not by folder names" },
+  ],
+};
+
+const DATA_PACKAGES = ["customers", "investors", "money"];
+
+/** Whether a segment is private (P-22). */
+export const isPrivate = (segment) => segment.startsWith("_");
+
+/** Whether a route's file pattern may reach a venture file: every private segment of the file is named, as it is, in the pattern (P-22). */
+export function routable(file, pattern) {
+  const ps = pattern.split("/");
+  return file.split("/").every((s, i) => !isPrivate(s) || ps[i] === s);
+}
+
+// Every entry under a folder, as venture-relative paths, stopping at nested ventures and dot folders other than reserved ones.
+function walk(dir, sub = "") {
+  const d = join(dir, sub);
+  return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+    const rel = sub ? `${sub}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      if (e.name === ".git" || e.name === "node_modules") return [];
+      if (existsSync(join(d, e.name, "venture.json"))) return [{ path: rel, dir: true, venture: true }];
+      return [{ path: rel, dir: true }, ...walk(dir, rel)];
+    }
+    return [{ path: rel, dir: false }];
+  });
+}
+
+/** Checks a venture folder's private folders and reserved names. { errors, warnings, private } */
+export function structure(dir) {
+  const errors = [], warnings = [], privateFolders = [];
+  if (!existsSync(join(dir, "venture.json"))) return { errors: [`${dir} has no venture.json`], warnings, private: privateFolders };
+  for (const e of walk(dir)) {
+    const segs = e.path.split("/");
+    const name = segs.at(-1), parent = segs.slice(0, -1).join("/");
+    if (e.venture) continue;
+    if (e.dir && isPrivate(name)) privateFolders.push({ folder: `${e.path}/`, holds: PRIVATE[name] ?? "private: never routed, never released (P-22)" });
+    if (e.dir && name === "_drafts" && parent) errors.push(`${e.path}/: _drafts/ is reserved for the venture root, where Naive writes held drafts (P-32)`);
+    if (!e.dir && segs[0] === "_drafts" && segs.length === 2 && !name.endsWith(".draft") && name !== ".gitkeep") errors.push(`${e.path}: only Naive's .draft files belong in _drafts/ (P-32)`);
+    if (e.dir && name === "_streams" && !DATA_PACKAGES.includes(parent)) errors.push(`${e.path}/: _streams/ belongs directly under a data package (${DATA_PACKAGES.join(", ")}) (P-32)`);
+    if (!e.dir && ["naive.config.json", "provenance.jsonl"].includes(name) && parent) errors.push(`${e.path}: ${name} is read only at the venture root; move it or rename it (P-32)`);
+    if (e.dir && name === ".release" && parent) errors.push(`${e.path}/: .release/ is reserved for the venture root (P-32)`);
+    if (RESERVED.future[name] && !segs.some(isPrivate)) warnings.push(`${e.path}: ${name} is reserved for ${RESERVED.future[name]}; rename it so a later Naive does not read it as that (P-32)`);
+    if (e.dir) for (const s of RESERVED.shapes) {
+      if (!s.re.test(name)) continue;
+      if (s.name === "(group)") {
+        if (parent) errors.push(`${e.path}/: a route group folder sits at the venture root (P-36)`);
+        const inside = readdirSync(join(dir, e.path)).filter((f) => f !== "AGENTS.md" && f !== ".gitkeep");
+        if (inside.length) errors.push(`${e.path}/: ${s.rule}; move ${inside.join(", ")} into its package`);
+      } else warnings.push(`${e.path}/: ${s.name} is ${s.rule} (P-32)`);
+    }
+  }
+  return { errors, warnings, private: privateFolders };
+}
+
+const PACKAGE_NAMES = () => existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : [];
+const pkgOf = (n) => load(join(repo, "packages", n, "package.json"));
+const FUNCTIONS = () => load(join(repo, "operations/departments.json")).departments.map((d) => d.id);
+
+/**
+ * The manifest venture.json declares (P-3), with what is derived when it does not declare it:
+ * identity, phase, governance, function owners, and the packages and kits in use.
+ */
+export async function manifest(dir) {
+  const v = load(join(dir, "venture.json"));
+  const names = PACKAGE_NAMES();
+  let derived = null;
+  if (!v.packages) {
+    // The packages that fit the phase now, plus every package that already holds a record.
+    const { packages } = await import("./packages.mjs");
+    const p = packages(dir);
+    const holding = names.filter((n) => { const k = pkgOf(n); return (k.records ?? []).length && existsSync(join(dir, n)) && readdirSync(join(dir, n)).some((f) => /\.(json|md|mdx)$/.test(f)); });
+    derived = [...new Set([...p.core.filter((x) => x.in === "now").map((x) => x.id), ...holding])];
+  }
+  const used = v.packages ?? derived;
+  const owners = v.functions ?? {};
+  const fnOf = (n) => { const k = names.includes(n) ? pkgOf(n) : {}; return k.function ?? k.department ?? null; };
+  const solo = !(v.members?.length);
+  const functions = [...new Set(used.map(fnOf).filter(Boolean))].map((f) => ({ function: f, owner: owners[f]?.owner ?? (solo ? "the founder" : null), declared: !!owners[f], packages: used.filter((n) => fnOf(n) === f) }));
+  for (const [f, o] of Object.entries(owners)) if (!functions.some((x) => x.function === f)) functions.push({ function: f, owner: o.owner, declared: true, packages: [] });
+  return {
+    identity: { id: v.id, name: v.name, kind: v.kind ?? "venture", parent: v.parent, owner: v.owner, status: v.status },
+    phase: v.phase,
+    governance: { governed_by: v.governed_by ?? null, legal_form: v.form?.legal_form ?? "none", members: v.members ?? [], decision_rights: existsSync(join(dir, "governance/decision-rights.json")) ? "governance/decision-rights.json" : "the framework's template" },
+    functions,
+    packages: { declared: !!v.packages, list: used.map((n) => ({ name: n, kind: names.includes(n) ? pkgOf(n).kind : null, known: names.includes(n) })) },
+    kits: (v.kits ?? []).map((k) => ({ ...k, note: "a kit is Mentura's; the framework checks only that it names a package the venture uses" })),
+  };
+}
+
+/** Errors in what venture.json declares (P-3): unknown packages and functions, kits extending a package not in use, an owner missing. */
+export function checkManifest(dir) {
+  const v = load(join(dir, "venture.json"));
+  const names = PACKAGE_NAMES(), fns = FUNCTIONS();
+  const errors = [];
+  for (const n of v.packages ?? []) if (!names.includes(n)) errors.push(`venture.json packages: ${n} is not a Naive package (one of ${names.join(", ")})`);
+  for (const [f, o] of Object.entries(v.functions ?? {})) {
+    if (!fns.includes(f)) errors.push(`venture.json functions: ${f} is not a function (one of ${fns.join(", ")})`);
+    if (!o?.owner) errors.push(`venture.json functions: ${f} has no owner; every function has one accountable owner`);
+  }
+  for (const k of v.kits ?? []) {
+    if (!names.includes(k.extends)) errors.push(`venture.json kits: ${k.id} extends ${k.extends}, which is not a Naive package`);
+    else if (v.packages && !v.packages.includes(k.extends)) errors.push(`venture.json kits: ${k.id} extends ${k.extends}, which the venture does not list in packages`);
+  }
+  return errors;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  if (args[0] === "manifest") {
+    if (!args[1] || !existsSync(join(args[1], "venture.json"))) { console.error("usage: node schema/structure.mjs manifest <venture dir>"); process.exit(2); }
+    console.log(JSON.stringify(await manifest(args[1]), null, 2));
+    process.exit(0);
+  }
+  const dir = args.find((a) => !a.startsWith("--"));
+  if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) { console.error("usage: node schema/structure.mjs <venture dir> [--json] | manifest <venture dir>"); process.exit(2); }
+  const s = structure(dir);
+  if (existsSync(join(dir, "venture.json"))) s.errors.push(...checkManifest(dir));
+  if (args.includes("--json")) console.log(JSON.stringify(s, null, 2));
+  else {
+    for (const w of s.warnings) console.warn(`warning: ${w}`);
+    if (s.errors.length) console.error(s.errors.join("\n"));
+    else console.log(`structure holds: ${s.private.length} private folders, no reserved name misused`);
+  }
+  process.exit(s.errors.length ? 1 : 0);
+}

package/schema/systems-catalog.json

@@ -0,0 +1,126 @@
+{
+  "version": "0.1.0",
+  "note": "Systems a venture's functions keep their truth in (EE-083), offered at create-venture and recorded in knowledge/sources.json `functions`. connect names the code that reaches a system; a system without it is recorded as a pointer until a connector exists.",
+  "systems": {
+    "local-repo": {
+      "label": "A local code repository",
+      "kind": "code",
+      "address": "a folder path",
+      "connect": null
+    },
+    "github": {
+      "label": "GitHub",
+      "kind": "code",
+      "address": "owner/name",
+      "connect": "knowledge/connectors: the github connector reads records from it (knowledge/sources.json)"
+    },
+    "vercel": {
+      "label": "Vercel",
+      "kind": "hosting and analytics",
+      "address": "team/project",
+      "connect": null
+    },
+    "cloudflare": {
+      "label": "Cloudflare",
+      "kind": "hosting and analytics",
+      "address": "account/zone or Pages project",
+      "connect": null
+    },
+    "stripe": {
+      "label": "Stripe",
+      "kind": "payments and sales",
+      "address": "account id (acct_...)",
+      "connect": null
+    },
+    "square": {
+      "label": "Square",
+      "kind": "payments and sales",
+      "address": "location or merchant id",
+      "connect": null
+    },
+    "shopify": {
+      "label": "Shopify",
+      "kind": "store and sales",
+      "address": "store domain (name.myshopify.com)",
+      "connect": null
+    },
+    "rho": {
+      "label": "Rho",
+      "kind": "bank and spend",
+      "address": "sandbox, or live with RHO_API_TOKEN",
+      "connect": "platform/integrations/rho.mjs sync: accounts, transactions and a summary, as pointers in money/"
+    },
+    "google-drive": {
+      "label": "Google Drive",
+      "kind": "documents",
+      "address": "folder URL",
+      "connect": null
+    },
+    "docusign": {
+      "label": "DocuSign",
+      "kind": "signatures",
+      "address": "account",
+      "connect": null
+    },
+    "local-folder": {
+      "label": "A local folder",
+      "kind": "documents",
+      "address": "a folder path",
+      "connect": null
+    }
+  },
+  "functions": {
+    "products": [
+      "local-repo",
+      "github",
+      "vercel",
+      "cloudflare"
+    ],
+    "marketing-and-sales": [
+      "vercel",
+      "cloudflare",
+      "stripe",
+      "square",
+      "shopify"
+    ],
+    "customer-service": [
+      "stripe",
+      "shopify",
+      "square"
+    ],
+    "finance": [
+      "rho",
+      "stripe",
+      "square",
+      "shopify"
+    ],
+    "risk-and-compliance": [
+      "google-drive",
+      "docusign",
+      "local-folder"
+    ],
+    "legal": [
+      "google-drive",
+      "docusign",
+      "local-folder"
+    ],
+    "it": [
+      "github",
+      "vercel",
+      "cloudflare"
+    ],
+    "external-relationships": [
+      "google-drive",
+      "local-folder"
+    ],
+    "service-delivery": [
+      "local-folder",
+      "google-drive"
+    ],
+    "supply-chain": [
+      "shopify",
+      "square",
+      "local-folder"
+    ]
+  }
+}

package/schema/systems-catalog.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "systems-catalog.schema.json",
+  "title": "Systems catalog",
+  "description": "The systems of record create-venture offers per function (schema/systems-catalog.json): each system's kind, what its address looks like, and the code that connects to it, if any.",
+  "type": "object",
+  "required": [
+    "version",
+    "systems",
+    "functions"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "systems": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "kind",
+          "address",
+          "connect"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string"
+          },
+          "connect": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      }
+    },
+    "functions": {
+      "type": "object",
+      "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": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/team-plan.schema.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "team-plan.schema.json",
+  "title": "Team plan",
+  "description": "Who the venture needs, agent or person, when, with what authority, and where a human stays in the loop (EE-029), at <venture>/operations/team-plan.json. Tasks cite the agent capability register; recruiting briefs say what each open person role is for.",
+  "type": "object",
+  "required": [
+    "venture",
+    "roles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "note": {
+      "type": "string"
+    },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "occupant",
+          "needed_by",
+          "status"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "A role id from the role registry, or the venture's own"
+          },
+          "name": {
+            "type": "string",
+            "description": "Required for a role not in the registry"
+          },
+          "occupant": {
+            "enum": [
+              "agent",
+              "person"
+            ]
+          },
+          "needed_by": {
+            "enum": [
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ]
+          },
+          "status": {
+            "enum": [
+              "filled",
+              "open",
+              "planned"
+            ]
+          },
+          "why": {
+            "type": "string"
+          },
+          "authority": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Decision classes delegated to this role"
+          },
+          "tasks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "capability"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "capability": {
+                  "type": "string"
+                },
+                "human_loop": {
+                  "type": "string",
+                  "description": "The person role that decides, reviews or does the part agents cannot"
+                }
+              }
+            }
+          },
+          "routes": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "The routes this role may reach (robots, EE-032), as globs over routes such as purpose/** or purpose/product/*. Left out, the role may reach every route; gates still apply. When given, read defaults to every route and write to none.",
+            "properties": {
+              "read": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "write": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "recruiting": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "role",
+          "brief"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "role": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "cofounder",
+              "hire",
+              "contractor",
+              "advisor",
+              "investor"
+            ]
+          },
+          "brief": {
+            "type": "string",
+            "description": "A recruiting brief, relative to the venture folder"
+          },
+          "channels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "assisted_by": {
+            "type": "string",
+            "description": "The agent role that drafts, searches and screens"
+          }
+        }
+      }
+    }
+  }
+}