naive-framework 0.0.0-stage → 0.1.0

package/schema/data-model.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "data-model.schema.json",
+  "title": "Data model",
+  "description": "The shape of schema/data-model.json (EE-018): every record type of the ecosystem, the layer that owns it, its schema, where its records live and what each references. schema/check-data-model.mjs checks it against the repository.",
+  "type": "object",
+  "required": [
+    "version",
+    "layers",
+    "records",
+    "ignore"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "layers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "records": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "layer",
+          "level",
+          "schema",
+          "paths"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "layer": {
+            "description": "The owning layer, or system for records every layer shares",
+            "enum": [
+              "system",
+              "purpose",
+              "knowledge",
+              "operations",
+              "evidence",
+              "governance",
+              "interface"
+            ]
+          },
+          "level": {
+            "description": "method: this repo's own records; workspace: one per builder; venture: inside a venture folder",
+            "enum": [
+              "method",
+              "workspace",
+              "venture"
+            ]
+          },
+          "schema": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Path to the schema that governs it, or null when it has none yet"
+          },
+          "form": {
+            "enum": [
+              "json",
+              "json-list",
+              "markdown",
+              "prose",
+              "json-lines"
+            ],
+            "description": "Default json. json-list: the file holds a list of records. json-lines: one record per line, append-only"
+          },
+          "decision_class": {
+            "type": "string",
+            "description": "The decision class (governance/venture-template/decision-rights.json) a write of this record is. When the venture's decision rights put the class at escalate or recommend-approve, an agent's write through the router is held as a draft for a person to accept (EE-032)"
+          },
+          "paths": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            },
+            "description": "Globs from the repo root"
+          },
+          "contains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Record types that live inside this one's folder"
+          },
+          "refs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "field",
+                "to",
+                "checked_by"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "field": {
+                  "type": "string"
+                },
+                "to": {
+                  "type": "string",
+                  "description": "A record type id, or a parenthesised name for a non-record target"
+                },
+                "checked_by": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The check that resolves this reference, or null when nothing does yet"
+                }
+              }
+            }
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ignore": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/decision-analytics.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Decision analytics (EE-072): how many decisions of each type each function of the venture has made,
+// open against decided, in whose words, in which phase, and what their outcomes were. Like Next.js's
+// instrumentation beside Vercel Analytics: the framework counts from the decision records already in
+// the venture (EE-054, EE-058); ranking decisions by impact over time is the next view, and is
+// listed under `next` rather than computed.
+//
+//   node schema/decision-analytics.mjs <venture dir>
+//
+// Output is data (JSON), never a view: rendering it belongs to the platform, or to a visualization
+// skill when Naive runs inside another harness such as Claude Code, Codex or Cursor (Torian, 2026-10-28).
+//
+// Function: the core package that holds the record a decision decides (EE-069, EE-071); foundation
+// statements and decisions about venture.json belong to Foundation; anything else is "Venture".
+// Type: the record type or foundation statement it decides (problem, product, mission...), so counts
+// answer "which kinds of decision has each function made". A decision record may set `type`.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decisions } from "./decisions.mjs";
+import { HOME, PACKAGES, TITLES } from "./packages.mjs";
+
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+const titleOf = (t) => ({ icp: "ICP", "venture-core": "Core product" })[t] ?? TITLES[t] ?? t.replace(/^validation-/, "").replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
+const FUNCTION_OF = { ...HOME, "venture-core": "foundation", brand: "marketing" };
+const DECIDED = new Set(["decided", "accepted"]);
+const OPEN = new Set(["now", "overdue", "waiting", "stale", "later"]);
+
+/** Counts over a venture's decisions; nothing is written. */
+export function analytics(dir, now) {
+  const r = decisions(dir, now);
+  const rows = r.decisions.filter((d) => d.source !== "root").map((d) => {
+    const raw = d.file ? load(join(dir, d.file)) : {};
+    const record = d.decides?.record ?? null;
+    // A foundation statement belongs to the strategic foundation whatever record holds it; so does a
+    // decision about venture.json itself (the core product, the team).
+    const statement = d.source === "foundation" ? d.id.replace(/^foundation-/, "") : null;
+    const fn = statement || d.part_of === "foundation" || d.decides?.path === "venture.json" ? "foundation" : FUNCTION_OF[record] ?? null;
+    const state = DECIDED.has(d.status) ? "decided" : OPEN.has(d.render) ? "open" : d.render;
+    const pv = d.provenance ?? raw.provenance ?? null;
+    return {
+      id: d.id, question: d.question, kind: d.source === "draft" ? "acceptance" : d.source === "foundation" ? "foundation statement" : "decision",
+      type: raw.type ?? titleOf(statement ?? record ?? d.id), function: fn ? PACKAGES.core[fn].title : "Venture", function_id: fn ?? "venture",
+      state, render: d.render, decided_by: pv?.approved_by ?? null, decided_at: pv?.approved_at ?? null, phase: pv?.phase ?? null,
+      wording: state === "decided" ? (pv?.wording ?? "unknown") : null,
+      outcomes: (raw.outcomes ?? []).map((o) => o.result ?? "pending"),
+    };
+  });
+  const count = (xs, key) => Object.entries(xs.reduce((m, x) => ((m[key(x)] = (m[key(x)] ?? 0) + 1), m), {})).sort((a, b) => b[1] - a[1]).map(([k, n]) => ({ key: k, n }));
+  const functions = [...new Set(rows.map((x) => x.function))].map((f) => {
+    const xs = rows.filter((x) => x.function === f);
+    return { function: f, id: xs[0].function_id, total: xs.length, decided: xs.filter((x) => x.state === "decided").length, open: xs.filter((x) => x.state === "open").length,
+      types: count(xs, (x) => x.type).map(({ key, n }) => ({ type: key, n, decided: xs.filter((x) => x.type === key && x.state === "decided").length })) };
+  }).sort((a, b) => b.total - a.total || a.function.localeCompare(b.function));
+  const decided = rows.filter((x) => x.state === "decided");
+  const outcomes = rows.flatMap((x) => x.outcomes);
+  const days = count(decided.filter((x) => x.decided_at), (x) => x.decided_at.slice(0, 10)).sort((a, b) => a.key.localeCompare(b.key));
+  return {
+    venture: r.venture, phase: r.phase, total: rows.length, decided: decided.length, open: rows.filter((x) => x.state === "open").length,
+    functions, types: count(rows, (x) => x.type), kinds: count(rows, (x) => x.kind),
+    wording: count(decided, (x) => x.wording), by: count(decided.filter((x) => x.decided_by), (x) => x.decided_by), phases: count(decided.filter((x) => x.phase), (x) => x.phase),
+    outcomes: { total: outcomes.length, ...Object.fromEntries(["met", "partly", "missed", "pending"].map((k) => [k, outcomes.filter((o) => o === k).length])) },
+    over_time: days.map(({ key, n }) => ({ day: key, decided: n })),
+    decisions: rows,
+    next: [
+      "Highest-impact decisions over time: a Score of each decision's impact (System 1), combined in code with its recorded outcomes",
+      "Projected against actual outcomes, once outcomes are recorded with results",
+      "How long decisions survive before they are revisited",
+    ],
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir) { console.error("usage: node schema/decision-analytics.mjs <venture dir>"); process.exit(2); }
+  console.log(JSON.stringify(analytics(dir), null, 2));
+}

package/schema/decision-record.schema.json

@@ -0,0 +1,290 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "decision-record.schema.json",
+  "title": "Decision record",
+  "description": "One decision a venture has to make, in a decisions/ folder beside the record it decides (EE-054), like a Next.js file beside its route: decisions/<record>[.<topic>].decision.json decides <record>.json in the folder that holds decisions/. The decision log (decision.schema.json) stays the append-only history; this is the live decision. node schema/decisions.mjs gathers them into the decision matrix.",
+  "type": "object",
+  "required": [
+    "id",
+    "question",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Unique within the venture. The roots venture and foundation are reserved."
+    },
+    "question": {
+      "type": "string",
+      "description": "What has to be decided, as a question"
+    },
+    "ideas": {
+      "type": "array",
+      "description": "The ideas in the founder's idea dump this decision comes from, by id (purpose/ideas/map.mdx), so a decision can be traced back to the founder's own words (EE-061)",
+      "items": {
+        "type": "string",
+        "pattern": "^i-[0-9]+$"
+      }
+    },
+    "decides": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What the decision settles: a record type, a venture-relative file, or both. Defaults to the record its file name names.",
+      "properties": {
+        "record": {
+          "type": "string",
+          "description": "A record type in schema/data-model.json"
+        },
+        "path": {
+          "type": "string",
+          "description": "A venture-relative file, such as purpose/icp.json"
+        }
+      }
+    },
+    "statement": {
+      "type": "string",
+      "description": "The strategic-foundation statement this decision settles (purpose/strategic-foundation.json), if any. It then stands in for that statement in the matrix and is part of the foundation."
+    },
+    "layer": {
+      "enum": [
+        "purpose",
+        "knowledge",
+        "operations",
+        "evidence",
+        "governance",
+        "interface",
+        "system"
+      ],
+      "description": "The layer it belongs to; defaults to the decided record's layer"
+    },
+    "parent": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The decision this one depends on. Defaults to foundation for a foundation record, else venture."
+    },
+    "boundary": {
+      "enum": [
+        "fail-closed",
+        "fail-open",
+        "inherit"
+      ],
+      "default": "inherit",
+      "description": "fail-closed: while this decision is open, decisions under it wait and agents only draft. fail-open: work under it goes on. inherit: the parent's boundary. The venture root and the foundation fail closed; a product fails open (EE-054)."
+    },
+    "needed_in": {
+      "enum": [
+        "discovery",
+        "validation",
+        "beachhead",
+        "scale",
+        "platform"
+      ],
+      "description": "The phase in which it must be made. One needed in a later phase than the venture's is speculative and held back (EE-057)."
+    },
+    "due": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When it must be decided, for a decision with a real deadline (a launch, a hackathon, a filing). An open decision past its due time renders overdue; a due time overrides needed_in, so a dated decision is never held back as later."
+    },
+    "status": {
+      "enum": [
+        "open",
+        "decided",
+        "deferred",
+        "withdrawn"
+      ]
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "answer": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "decided_by": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Who decided: a person's name. An agent never decides a fail-closed decision. Deprecated in favour of provenance.approved_by, which it must equal when both are present."
+    },
+    "decided_at": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "date-time"
+    },
+    "logged_as": {
+      "type": "string",
+      "description": "The decision log entry that records it, such as D-012 or EE-054"
+    },
+    "note": {
+      "type": "string"
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who worded and who approved the decision, when, and in which phase (EE-058). An agent's wording waits with drafted_by alone; a decided decision needs approved_by, approved_at and phase.",
+      "required": [
+        "drafted_by"
+      ],
+      "properties": {
+        "drafted_by": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "person",
+                "agent",
+                "framework"
+              ],
+              "description": "framework: Naive asked the question itself, as a convention (the product foundation); a person still answers it"
+            },
+            "id": {
+              "type": "string",
+              "description": "The person's name or the agent's id"
+            }
+          },
+          "description": "Who wrote the wording"
+        },
+        "approved_by": {
+          "type": "string",
+          "description": "The person who approved the wording or changed it. Never an agent."
+        },
+        "approved_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "phase": {
+          "enum": [
+            "discovery",
+            "validation",
+            "beachhead",
+            "scale",
+            "platform"
+          ],
+          "description": "The venture's phase when it was approved"
+        },
+        "wording": {
+          "enum": [
+            "approved",
+            "changed",
+            "own"
+          ],
+          "description": "approved: the drafted wording as it was; changed: the approver altered it; own: the approver wrote it"
+        },
+        "authority": {
+          "type": "string",
+          "description": "The decision class in governance/decision-rights.json under which the approver could decide, when authority was delegated"
+        },
+        "via": {
+          "type": "string",
+          "description": "Where the approval was given, such as the Decision Docket or a decision card"
+        }
+      }
+    },
+    "outcomes": {
+      "type": "array",
+      "description": "What the decision is expected to achieve, and later what happened; the evaluations it is tested against (EE-058). Outcomes, not activities.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "projected"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "projected": {
+            "type": "string",
+            "description": "The outcome expected"
+          },
+          "by": {
+            "type": "string",
+            "description": "When it should be visible: a date-time, a date or a phase. A pending outcome past a date-time or date is due for its actual result."
+          },
+          "measure": {
+            "type": "string",
+            "description": "How it will be checked"
+          },
+          "actual": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "What happened"
+          },
+          "result": {
+            "enum": [
+              "pending",
+              "met",
+              "partly",
+              "missed"
+            ],
+            "default": "pending"
+          },
+          "recorded_by": {
+            "type": "string"
+          },
+          "recorded_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "unlocks": {
+      "type": "array",
+      "description": "Activities this decision opens that were closed before it (EE-058), and for whom",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "activity"
+        ],
+        "properties": {
+          "activity": {
+            "type": "string"
+          },
+          "for": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Roles, people or agents it opens for; empty means everyone"
+          },
+          "routes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The routes the activity uses, as globs such as operations/** (robots syntax). Until the decision is made, the router refuses agents those routes (for the actors in for, or every agent)."
+          }
+        }
+      }
+    }
+  }
+}

package/schema/decision-rights.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "decision-rights.schema.json",
+  "title": "Decision rights",
+  "description": "Who may decide what (EE-017). The template lives at governance/venture-template/decision-rights.json; a venture may tighten a class (move it to a higher level or a more senior owner) in <venture>/governance/decision-rights.json, and loosening one needs an owner decision. Levels follow RAPID and DACI: decide, decide-inform, recommend-approve, escalate.",
+  "type": "object",
+  "required": ["register", "classes"],
+  "properties": {
+    "register": { "const": "decision-rights" },
+    "updated": { "type": "string" },
+    "governed_by": { "type": "string" },
+    "template": { "type": "boolean", "description": "True for the template; a venture's file omits it or sets false" },
+    "extends": { "type": "string", "description": "A venture file: path to the template it tightens" },
+    "levels": { "type": "object", "additionalProperties": { "type": "string" } },
+    "note": { "type": "string" },
+    "classes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "owner", "level"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "description": { "type": "string" },
+          "owner": { "type": "string", "description": "Role id from the roles register" },
+          "level": { "enum": ["decide", "decide-inform", "recommend-approve", "escalate"] },
+          "condition": { "type": "string" },
+          "decision": { "type": "string", "description": "A venture file: the decision that tightened or loosened it" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/decision.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "decision.schema.json",
+  "title": "Decision log",
+  "description": "A decision log: the schema's own (docs/decisions/decisions.json, ids EE-NNN), or any venture's, with its own id prefix. Entries are appended, never rewritten; a changed decision is a new entry that supersedes the old one.",
+  "type": "object",
+  "required": ["log", "prefix", "decisions"],
+  "properties": {
+    "log": { "type": "string", "description": "Whose decisions these are" },
+    "prefix": { "type": "string", "pattern": "^[A-Z]+$", "description": "Id prefix, e.g. EE for the schema itself" },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "date", "decision", "status"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Z]+-\\d{3}$" },
+          "date": { "type": "string", "format": "date" },
+          "decision": { "type": "string" },
+          "why": { "type": "string" },
+          "status": { "enum": ["proposed", "in-force", "superseded", "withdrawn"] },
+          "supersedes": { "type": "array", "items": { "type": "string" } },
+          "related": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}