naive-framework 0.0.0-stage → 0.2.0

package/schema/exit.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "exit.schema.json",
+  "title": "Exit",
+  "description": "How the venture might end and what each owner would get, at <venture>/governance/exit.json (EE-022): the exit paths it keeps open and the sale values to model. Payouts are never typed here: schema/payouts.mjs computes them from ownership.json for each scenario.",
+  "type": "object",
+  "required": [
+    "paths"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "paths": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "stance"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "enum": [
+              "acquisition",
+              "ipo",
+              "secondary-sale",
+              "merger",
+              "management-buyout",
+              "wind-down",
+              "hold"
+            ],
+            "description": "hold: no exit, the owners keep it"
+          },
+          "stance": {
+            "enum": [
+              "preferred",
+              "open",
+              "ruled-out"
+            ]
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "scenarios": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "value"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "value": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Proceeds to the owners after debts and costs"
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/foundation.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Reports a venture's strategic foundation (EE-051, EE-052): for each question of the Five Ws and How plus
+// whether (purpose/strategic-foundation.json), the record attributes that answer it, and whether
+// each is confirmed, drafted by an agent, waiting as a draft, or missing. This is what a founder
+// keeps in front of them; a platform renders it always visible. Behaviors:
+// purpose/kits/validation/features/strategic-foundation.feature.
+//
+//   node schema/foundation.mjs <venture dir> [--json]
+//
+// Status: confirmed (the last write was a person's, or a person accepted it), agent (an agent
+//   wrote it and no person has confirmed it), draft (a draft waits in _drafts/), missing, planned
+//   (no record type yet). A statement an agent drafted is not the founder's until confirmed.
+// Exit 1 when the frame names a record type the data model lacks, or an ICP names a problem form
+// the problem record lacks.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+export const FRAME = load(join(repo, "purpose/strategic-foundation.json"));
+const MODEL = load(join(repo, "schema/data-model.json"));
+
+const get = (o, path) => path.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
+const filled = (v) => v !== undefined && v !== null && v !== "" && !(Array.isArray(v) && !v.length);
+
+/** Venture-relative files of a record type: one file, or every item of a collection. */
+export function filesOf(dir, type) {
+  const r = MODEL.records.find((x) => x.id === type);
+  const gs = (r?.paths ?? []).filter((p) => p.startsWith("instance/**/")).map((p) => p.slice("instance/**/".length));
+  const found = [];
+  for (const g of gs) {
+    if (!g.includes("*")) { if (existsSync(join(dir, g))) found.push(g); continue; }
+    const star = g.indexOf("*");
+    const folder = g.slice(0, star), rest = g.slice(star + 1);
+    if (rest.includes("*")) continue;
+    const d = join(dir, folder);
+    if (existsSync(d)) for (const f of readdirSync(d)) if (f.endsWith(rest)) found.push(folder + f);
+  }
+  if (found.length) return found;
+  const drafted = gs.filter((g) => !g.includes("*") && existsSync(join(dir, `_drafts/${g.replace(/\//g, "__")}.draft`)));
+  return drafted.length ? drafted : gs.slice(0, 1);
+}
+
+/** Whether a person confirmed one statement in a file: their write or accept of the file, or a
+ *  confirm of that statement, after the last write by anyone else. */
+export function confirmedIn(dir, file, id, seen = new Set()) {
+  if (seen.has(file)) return false;
+  seen.add(file);
+  const log = join(dir, "provenance.jsonl");
+  if (!existsSync(log)) return false;
+  const draft = `_drafts/${file.replace(/\//g, "__")}.draft`;
+  const es = readFileSync(log, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)).filter((e) => e.entity === file || e.entity === draft);
+  const lastAgentWrite = es.findLastIndex((e) => e.entity === file && e.activity !== "confirm" && e.activity !== "move" && e.activity !== "release" && e.agent?.kind !== "person" && e.activity !== "accept");
+  const direct = es.some((e, i) => i > lastAgentWrite && e.entity === file && (e.activity === "accept" || (e.agent?.kind === "person" && e.activity !== "confirm" && e.activity !== "move") || (e.activity === "confirm" && e.statement === id)));
+  if (direct) return true;
+  return es.filter((e) => e.activity === "move" && e.entity === file).flatMap((e) => e.derived_from ?? []).some((p) => confirmedIn(dir, p, id, seen));
+}
+
+/** Each foundation statement of a venture, with its status and value. */
+export function foundation(dir) {
+  const report = FRAME.questions.map((q) => ({ question: q.id, ask: q.ask, statements: q.statements.map((s) => {
+    if (s.derived_from) return s;
+    if (!s.record) return { id: s.id, status: "planned", note: s.note ?? null };
+    const files = filesOf(dir, s.record);
+    // A retired product no longer answers for the venture.
+    const values = files.filter((f) => existsSync(join(dir, f)) && load(join(dir, f)).status !== "retired").map((f) => ({ f, v: get(load(join(dir, f)), s.attribute) })).filter((x) => filled(x.v));
+    const drafts = files.filter((f) => existsSync(join(dir, `_drafts/${f.replace(/\//g, "__")}.draft`)));
+    if (!values.length) return { id: s.id, record: s.record, attribute: s.attribute, status: drafts.length ? "draft" : "missing" };
+    // A record with no log entry existed before the log; a person's baseline or write confirms it.
+    const confirmed = values.every(({ f }) => confirmedIn(dir, f, s.id));
+    return { id: s.id, record: s.record, attribute: s.attribute, status: drafts.length ? "draft" : confirmed ? "confirmed" : "agent",
+      value: values.length === 1 && !files[0].includes("products/") ? values[0].v : Object.fromEntries(values.map(({ f, v }) => [f, v])) };
+  }) }));
+  // A derived statement takes its source's status and shows the primary ICP profile's short form.
+  const all = report.flatMap((q) => q.statements);
+  for (const q of report) q.statements = q.statements.map((s) => {
+    if (!s.derived_from) return s;
+    const src = all.find((x) => x.id === s.derived_from) ?? { status: "missing" };
+    const out = { id: s.id, record: s.record, attribute: s.attribute, derived_from: s.derived_from, status: src.status };
+    const primary = Array.isArray(src.value) ? (src.value.find((p) => p.primary) ?? src.value[0]) : null;
+    if (primary) out.value = primary.short ?? primary.who;
+    return out;
+  });
+  return report;
+}
+
+export function problems(dir) {
+  const out = FRAME.questions.flatMap((q) => q.statements).filter((s) => s.record && !MODEL.records.some((r) => r.id === s.record)).map((s) => `frame: ${s.id} names record type ${s.record}, which the data model lacks`);
+  const there = (...fs) => fs.map((f) => join(dir, f)).find((p) => existsSync(p));
+  const icp = there("foundation/icp.json", "purpose/icp.json"), prob = there("foundation/problem.json", "purpose/validation/problem.json");
+  if (icp) {
+    const forms = new Set(existsSync(prob) ? (load(prob).forms ?? []).map((f) => f.id) : []);
+    for (const p of load(icp).profiles) for (const f of p.problem_forms ?? []) if (!forms.has(f)) out.push(`icp ${p.id}: problem form ${f} is not in the problem record`);
+    const primaries = load(icp).profiles.filter((p) => p.primary).length;
+    if (load(icp).profiles.length > 1 && primaries !== 1) out.push(`icp: ${primaries} primary profiles; exactly one is primary`);
+    // promised-to is derived from the ICP; a hand-written one that differs has drifted.
+    const p = load(icp).profiles.find((x) => x.primary) ?? load(icp).profiles[0];
+    const said = existsSync(join(dir, "venture.json")) ? load(join(dir, "venture.json")).core?.promised_to : undefined;
+    if (p && filled(said) && said !== (p.short ?? p.who)) out.push(`venture core.promised_to differs from the ICP's short form ("${p.short ?? p.who}"); it is derived from the ICP`);
+  }
+  return out;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const arg = process.argv[2];
+  if (!arg) { console.error("usage: node schema/foundation.mjs <venture or workspace dir> [--json]"); process.exit(2); }
+  const walk = (d) => existsSync(join(d, "venture.json")) ? [d] : readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && !e.name.startsWith("_")).flatMap((e) => walk(join(d, e.name)));
+  const dirs = walk(arg);
+  const errs = dirs.flatMap((d) => problems(d).map((p) => `${d}: ${p}`));
+  if (process.argv.includes("--json")) console.log(JSON.stringify(dirs.length === 1 ? foundation(dirs[0]) : Object.fromEntries(dirs.map((d) => [d, foundation(d)])), null, 2));
+  else for (const d of dirs) {
+    if (dirs.length > 1) console.log(`\n${d}`);
+    for (const q of foundation(d)) console.log(`${q.question.padEnd(8)} ${q.ask}\n${q.statements.map((s) => `         ${s.id.padEnd(16)} ${s.status}${s.value !== undefined ? `: ${JSON.stringify(s.value).slice(0, 90)}` : ""}`).join("\n")}`);
+  }
+  for (const e of errs) console.error(`FAIL  ${e}`);
+  process.exit(errs.length ? 1 : 0);
+}

package/schema/founder-agreement.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "founder-agreement.schema.json",
+  "title": "Founder agreement",
+  "description": "The summary of what founders agreed with each other, at <venture>/governance/founder-agreement.json (EE-022), with the full text (or the signed document's location) in founder-agreement.md beside it. Equity and vesting live in ownership.json and are not repeated here. Required once two or more founders share ownership.",
+  "type": "object",
+  "required": [
+    "founders",
+    "signed",
+    "document"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "signed": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "date",
+      "description": "null until every founder has signed"
+    },
+    "document": {
+      "type": "string",
+      "description": "Path to the prose agreement or the signed document"
+    },
+    "founders": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "holder",
+          "role",
+          "commitment",
+          "ip_assigned"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "holder": {
+            "type": "string",
+            "description": "Holder id in ownership.json"
+          },
+          "role": {
+            "type": "string"
+          },
+          "commitment": {
+            "enum": [
+              "full-time",
+              "part-time"
+            ]
+          },
+          "ip_assigned": {
+            "type": "boolean",
+            "description": "Has assigned to the venture the work and ideas they brought or make"
+          }
+        }
+      }
+    },
+    "departure": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "good_leaver": {
+          "type": "string"
+        },
+        "bad_leaver": {
+          "type": "string"
+        },
+        "buyback": {
+          "enum": [
+            "unvested-only",
+            "unvested-at-cost",
+            "none"
+          ]
+        }
+      }
+    },
+    "deadlock": {
+      "type": "string",
+      "description": "How founders break a tie"
+    }
+  }
+}

package/schema/founder.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "founder.schema.json",
+  "title": "Founder",
+  "description": "One founder of the venture (people/founders/<id>.json): role, the functions they own, when they joined, and where their founder agreement is. One file per founder, so each founder's record changes on its own.",
+  "type": "object",
+  "required": [
+    "id",
+    "name",
+    "role",
+    "hats",
+    "joined"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string"
+    },
+    "role": {
+      "enum": [
+        "founder",
+        "co-founder",
+        "general-partner"
+      ]
+    },
+    "hats": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "strategy",
+          "products",
+          "marketing-and-sales",
+          "supply-chain",
+          "service-delivery",
+          "customer-service",
+          "human-capital",
+          "it",
+          "finance",
+          "assets",
+          "risk-and-compliance",
+          "external-relationships",
+          "capabilities"
+        ]
+      },
+      "uniqueItems": true
+    },
+    "joined": {
+      "type": "string",
+      "format": "date"
+    },
+    "agreement": {
+      "type": "object",
+      "required": [
+        "path",
+        "signed"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "signed": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/schema/frame.schema.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "frame.schema.json",
+  "title": "Frame (decision library)",
+  "description": "One recurring venture problem, as a shape, at packages/<function>/frames/<id>.frame.json. A frame is to Naive what a component is to a React component library. It holds the goal, the decisions hidden in the founder's sentence, the premises that sentence assumes and the moves to attack them, and what current information a lookup must supply. It never holds an answer: no instrument, vendor, term or market norm, because those go stale and can be wrong. schema/frames.mjs matches a frame to the founder's words, reads the props from the venture's records, has a model judge each premise yes, no or unknown, and proposes the frame's decisions with open options for the founder to decide.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "functions",
+    "triggers",
+    "goal",
+    "premises",
+    "attacks",
+    "reframe",
+    "props",
+    "freshness",
+    "reasoning",
+    "emits"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "title": {
+      "type": "string"
+    },
+    "functions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+$"
+      },
+      "description": "The venture functions the problem belongs to; the first is the package the frame lives in"
+    },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "Sentences a founder says when they have this problem, in a founder's words"
+    },
+    "goal": {
+      "type": "string",
+      "description": "The end the decisions serve; {prop} placeholders are filled from the venture"
+    },
+    "premises": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "claim",
+          "attack"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "claim": {
+            "type": "string",
+            "description": "What the founder's sentence assumes, as a yes/no proposition about this venture"
+          },
+          "attack": {
+            "type": "string",
+            "description": "The premise attack applied to it, one of schema/frames.mjs ATTACKS"
+          },
+          "reads": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The props the judgment of this premise needs"
+          }
+        }
+      },
+      "description": "The chain the founder's sentence assumes, in order"
+    },
+    "attacks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "The premise attacks the frame uses (the hooks of the library)"
+    },
+    "dichotomy": {
+      "type": "string",
+      "description": "The trade the founder's sentence forces, asked as: is it false, a real trade-off, or a sequence?"
+    },
+    "reframe": {
+      "type": "string",
+      "description": "The better question the frame leaves the founder with; {prop} placeholders are filled from the venture"
+    },
+    "composes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Smaller frames this one is built from"
+    },
+    "props": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "The venture facts the frame reads, never stores: phase, goal, runway, revenue, cap_table, jurisdiction, control_rights"
+    },
+    "freshness": {
+      "type": "object",
+      "required": [
+        "look_for",
+        "max_age_days",
+        "cite"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "look_for": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "What a lookup must find, described as a problem, never as a named answer"
+        },
+        "filter_by": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "max_age_days": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cite": {
+          "type": "boolean",
+          "const": true
+        }
+      },
+      "description": "What current information the frame needs and how fresh it must be. The lookup itself is a kit's skill; the frame says only what to look for."
+    },
+    "reasoning": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "What a model that fetches the frame must do, in order"
+    },
+    "emits": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "question"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "question": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Options that describe the problem's own parts, never a named answer; options from a lookup are added at run time with their date and source"
+          },
+          "options_from": {
+            "enum": [
+              "frame",
+              "lookup"
+            ],
+            "default": "frame"
+          },
+          "layer": {
+            "enum": [
+              "purpose",
+              "knowledge",
+              "operations",
+              "evidence",
+              "governance",
+              "interface"
+            ]
+          },
+          "needed_in": {
+            "enum": [
+              "discovery",
+              "validation",
+              "beachhead",
+              "scale",
+              "platform"
+            ]
+          }
+        }
+      },
+      "description": "The decisions the frame proposes, each open for the founder to decide"
+    },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "facts",
+          "expect"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "facts": {
+            "type": "object",
+            "description": "The props of a worked venture"
+          },
+          "expect": {
+            "type": "object",
+            "description": "The premise verdicts and dichotomy a good judgment reaches for these facts"
+          }
+        }
+      },
+      "description": "Worked cases, to evaluate a model's judgments against"
+    }
+  }
+}