naive-framework 0.0.0-stage → 0.1.0

package/schema/handoff.schema.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "handoff.schema.json",
+  "title": "Handoff",
+  "description": "One unit of delegated work, stored at <venture>/operations/handoffs/<id>.json (EE-017). It is the machine half of handoff contract v2 (operations/handoff-v2.md): who holds it, which decision rights it carries, how it is checked, and where it stands. The brief (outcome, work, context) is prose in a Markdown file beside it. schema/check-ready.mjs checks it is ready before work starts; schema/check-execution.mjs checks it against the venture's decision rights and evidence.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "venture",
+    "role",
+    "brief",
+    "decision_classes",
+    "done_criteria",
+    "status",
+    "attempts",
+    "max_attempts",
+    "run_cap"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "title": {
+      "type": "string"
+    },
+    "venture": {
+      "type": "string",
+      "description": "Venture id"
+    },
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Product ids the work serves"
+    },
+    "governed_by": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Decision ids this executes (EE-NNN, G-NNN, D-NNN or an ADR path)"
+    },
+    "assignment": {
+      "type": "string",
+      "pattern": "^(A-[0-9]{3}|none)$",
+      "description": "Optional: the build-method assignment the work runs under, such as a MAD A-NNN, or none. MAD is a separate product, so Mentura records the reference and does not check it (EE-019, EE-038)"
+    },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files the work needs before it can start, from the repo root; check-ready.mjs makes sure they exist"
+    },
+    "role": {
+      "type": "string",
+      "description": "Role id from the roles register that holds it (builder, architect and so on)"
+    },
+    "brief": {
+      "type": "string",
+      "description": "Path to the Markdown brief, relative to this file"
+    },
+    "decision_classes": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string"
+      },
+      "description": "Decision-rights class ids the holder may use without reporting back. Anything outside them is escalated."
+    },
+    "done_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind",
+          "check"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "kind": {
+            "enum": [
+              "conformance",
+              "self-proof",
+              "review"
+            ],
+            "description": "conformance: an objective check run as a command, with no model and no reviewer. self-proof: the change exercised for real, with evidence attached (EE-006). review: fit to intent, judged by the named role."
+          },
+          "check": {
+            "type": "string",
+            "description": "The command to run, or for review the question the reviewer answers"
+          },
+          "reviewer": {
+            "type": "string",
+            "description": "Role id, for review criteria"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "ready",
+        "in-progress",
+        "escalated",
+        "done"
+      ],
+      "description": "draft until schema/check-ready.mjs passes and is recorded; then ready, in-progress, escalated or done"
+    },
+    "ready_check": {
+      "type": "object",
+      "required": [
+        "at",
+        "by",
+        "version",
+        "items"
+      ],
+      "properties": {
+        "at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "by": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "items": {
+          "type": "integer"
+        }
+      },
+      "description": "Written by check-ready.mjs --record when every readiness item passed, before execution started"
+    },
+    "claimed_by": {
+      "type": "string",
+      "description": "Session or run id of the holder"
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Session that wrote the handoff"
+    },
+    "parent_session_id": {
+      "type": "string",
+      "description": "Session that assigned it, for lineage"
+    },
+    "attempts": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "max_attempts": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 3
+    },
+    "run_cap": {
+      "type": "string",
+      "pattern": "^([0-9]+(m|h)|\\$[0-9]+)$",
+      "description": "Wall-clock or spend cap per run, such as 2h or $20"
+    },
+    "pr": {
+      "type": "string",
+      "description": "Pull request link once opened"
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Paths to eval or check results (evidence.schema.json) that prove the done-criteria"
+    },
+    "escalations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "class",
+          "question",
+          "to"
+        ],
+        "properties": {
+          "class": {
+            "type": "string",
+            "description": "The decision-rights class, or attempts or run-cap"
+          },
+          "question": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string",
+            "description": "Role id"
+          },
+          "blocks": {
+            "type": "string"
+          },
+          "continued": {
+            "type": "string"
+          },
+          "answer": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "lesson": {
+      "type": "string",
+      "description": "A failure that could recur, and the check one rung higher that would catch it (prose, skill, rule, static analysis, code)"
+    },
+    "publication": {
+      "type": "object",
+      "description": "Required when the handoff publishes (public-commitment in decision_classes or escalations): the channel and content rule in the venture's publication policy (EE-025)",
+      "required": [
+        "channel",
+        "content"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "channel": {
+          "type": "string"
+        },
+        "content": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/icp.schema.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "icp.schema.json",
+  "title": "Ideal customer profile",
+  "description": "Who the venture serves (EE-051), at <venture>/purpose/icp.json: the 'who' foundation statement. One or more profiles, one primary, each specific enough to go and find ten of them, with what they are trying to do, what gets in the way and who is out of scope. Gated like the telos: an agent's write is a draft the founder accepts.",
+  "type": "object",
+  "required": [
+    "venture",
+    "profiles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "decision": {
+      "type": "string",
+      "description": "The decision that set it, such as EE-045"
+    },
+    "profiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "who"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "who": {
+            "type": "string",
+            "description": "Who they are, specifically enough to find ten of them"
+          },
+          "short": {
+            "type": "string",
+            "description": "One line naming who they are; the venture's promised-to statement shows it (EE-052)"
+          },
+          "primary": {
+            "type": "boolean",
+            "description": "Exactly one profile is primary"
+          },
+          "customer": {
+            "enum": [
+              "b2b",
+              "b2c",
+              "b2g"
+            ]
+          },
+          "phases": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "discovery",
+                "validation",
+                "beachhead",
+                "scale",
+                "platform"
+              ]
+            },
+            "description": "The phases of their own venture they are in, when they are founders"
+          },
+          "traits": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "What must be true of them"
+          },
+          "jobs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "What they are trying to get done (jobs to be done)"
+          },
+          "problem_forms": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9-]+$"
+            },
+            "description": "Ids of the problem record's forms they have"
+          },
+          "where_to_find": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Where to reach them: communities, channels, events"
+          },
+          "not": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Who is out of scope, and why"
+          },
+          "buying_roles": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "initiator",
+                "user",
+                "influencer",
+                "decider",
+                "buyer",
+                "gatekeeper"
+              ]
+            },
+            "description": "The parts this profile plays in a purchase (the buying center: Webster and Wind 1972; initiator added by Bonoma 1982). One person may hold several; a solo founder or a consumer usually holds them all."
+          },
+          "reached_through": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Other profiles (ids) through whom the venture reaches this one, such as a channel partner in a B2B2C venture (EE-064)"
+          },
+          "customer_type": {
+            "type": "string",
+            "description": "The customer type from the marketing matrix (operations/marketing/site/matrix.json customer_types), when the founder sets it; otherwise it is judged from who (EE-063)"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/idea-graph.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "idea-graph.schema.json",
+  "title": "Idea graph",
+  "description": "The structured form of a founder's idea map (EE-060): a Merkle DAG. Each idea's hash covers its text and the hashes of the ideas it builds on, so a change upstream changes every hash downstream. Written by purpose/frameworks/idea-map/graph.mjs; it holds no decisions.",
+  "type": "object",
+  "required": ["version", "venture", "phase", "root", "judged_by", "nodes", "edges", "lanes", "next"],
+  "properties": {
+    "version": { "type": "string" },
+    "venture": { "type": "string" },
+    "phase": { "enum": ["discovery", "validation", "beachhead", "scale", "platform"] },
+    "created": { "type": "string" },
+    "source": { "type": "string", "description": "The idea map it was built from, with that file's hash" },
+    "root": { "type": "string", "description": "Hash over the hashes of the ideas nothing builds on: one value for the whole graph" },
+    "judged_by": { "enum": ["jev", "convention"], "description": "Who judged the dependencies: Jev's typed answers, or Naive's convention of which records build on which" },
+    "weights": { "type": "object", "additionalProperties": { "type": "number" } },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "hash", "text", "depth", "builds_on", "signal", "lane"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^i-\\d+$" },
+          "hash": { "type": "string", "pattern": "^[0-9a-f]{16}$" },
+          "text": { "type": "string", "description": "The founder's words, unchanged" },
+          "section": { "type": "string" },
+          "pillar": { "type": ["string", "null"] },
+          "departments": { "type": "array", "items": { "type": "string" } },
+          "records": { "type": "array", "items": { "type": "string" } },
+          "exists": { "type": "boolean" },
+          "depth": { "type": "integer", "minimum": 0, "description": "Longest chain of ideas before it: its column, left to right" },
+          "builds_on": { "type": "array", "items": { "type": "string" } },
+          "signal": { "type": "number", "minimum": 0, "maximum": 1 },
+          "parts": { "type": "object", "additionalProperties": { "type": "number" } },
+          "lane": { "type": "string" }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": { "type": "object", "required": ["from", "to", "p"], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "p": { "type": "number" }, "by": { "type": "string" } } }
+    },
+    "dropped": { "type": "array", "description": "Dependencies left out because they would have closed a cycle" },
+    "lanes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "mode", "ideas"],
+        "properties": {
+          "id": { "type": "string" },
+          "mode": { "enum": ["sync", "async"], "description": "sync: its ideas build on each other and move in order; async: it moves on its own, beside the other lanes" },
+          "ideas": { "type": "array", "items": { "type": "string" } },
+          "department": { "type": ["string", "null"] },
+          "signal": { "type": "number" },
+          "why": { "type": "string" }
+        }
+      }
+    },
+    "next": { "type": "array", "items": { "type": "string" }, "description": "The highest-signal ideas that build on nothing: what to develop next" }
+  }
+}

package/schema/init-venture.mjs

@@ -0,0 +1,98 @@
+// Creates an empty venture: its folder, one folder per starting layer, products/,
+// accounts/, the three pillars as stubs pointing to their guides (EE-010), a venture profile and a venture.json to fill in
+// (EE-011). Starting layers come from scaffold/defaults.json, by phase (EE-012).
+//
+//   node schema/init-venture.mjs <dir> <id> [--phase discovery] [--parent <id>] [--legal-form llc] [--layers purpose,governance]
+//
+// --layers turns on only the layers named, for a builder adopting part of the system (EE-030);
+// without it the phase's defaults apply.
+//
+// Creates new ventures only, like create-next-app: it refuses a directory that exists and is not empty,
+// so it can never overwrite a founder's files. An existing project comes in through naive port (EE-076).
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = join(here, "..");
+const { layers, formalized, pillars, readme } = JSON.parse(readFileSync(join(here, "scaffold/defaults.json"), "utf8"));
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(`--${name}`); return i < 0 ? null : args.splice(i, 2)[1]; };
+const phase = flag("phase") ?? "discovery", parent = flag("parent"), legalForm = flag("legal-form"), only = flag("layers");
+const [dir, id] = args;
+if (!dir || !id) { console.error("usage: node schema/init-venture.mjs <dir> <id> [--phase discovery] [--parent <id>] [--legal-form llc]"); process.exit(2); }
+if (!layers[phase]) { console.error(`unknown phase ${phase}: one of ${Object.keys(layers).join(", ")}`); process.exit(2); }
+if (existsSync(dir) && readdirSync(dir).length) { console.error(`${dir} already exists and is not empty: init creates new ventures only, and never writes into an existing project`); process.exit(1); }
+
+const ALL = ["purpose", "knowledge", "operations", "evidence", "governance", "interface"];
+const on = only !== null ? only.split(",").filter(Boolean) : [...layers[phase], ...(legalForm && legalForm !== "none" ? formalized : [])];
+const unknown = on.filter((l) => !ALL.includes(l));
+if (unknown.length) { console.error(`unknown layers: ${unknown.join(", ")}; one of ${ALL.join(", ")}`); process.exit(2); }
+mkdirSync(dir, { recursive: true });
+const venture = { id, name: id, parent: parent ?? null, phase };
+if (legalForm) venture.form = { legal_form: legalForm };
+if (phase !== "discovery") venture.core = { promise: "", promised_to: "", must_not: "", competence: "" };
+Object.assign(venture, { owner: "self", status: "active", profile: "profile.md", layers: {} });
+for (const layer of ALL) {
+  if (!on.includes(layer)) { if (only !== null || !["governance", "interface"].includes(layer)) venture.layers[layer] = false; continue; }
+  mkdirSync(join(dir, layer), { recursive: true });
+  writeFileSync(join(dir, layer, "README.md"), `# ${layer}\n\n${readme[layer]}\n`);
+  venture.layers[layer] = { location: `${layer}/` };
+}
+for (const sub of ["products", "accounts"]) { mkdirSync(join(dir, sub), { recursive: true }); writeFileSync(join(dir, sub, ".gitkeep"), ""); }
+// The package folder layout (EE-070). Old layer folders above stay for one release.
+for (const sub of ["raw/dump", "raw/sources", "ideas", "foundation", "validation", "product", "marketing", "finance", "people", "customers", "investors", "money", "decisions", "evidence", "public", "_private", "_drafts", ".release"]) {
+  mkdirSync(join(dir, sub), { recursive: true });
+}
+mkdirSync(join(dir, "pillars"), { recursive: true });
+for (const [name, what] of Object.entries(pillars.stubs)) {
+  const guide = relative(join(dir, "pillars"), join(repo, pillars.guides, `${name}.md`));
+  writeFileSync(join(dir, "pillars", `${name}.md`), `# ${name[0].toUpperCase() + name.slice(1)} pillar\n\n${what}\n\nGuide: [${name} pillar](${guide})\n`);
+}
+writeFileSync(join(dir, "profile.md"), `# ${id}\n\nWhat this venture is, in a few sentences. Its machine fields are in venture.json (EE-011).\n\n## Changelog\n`);
+writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
+// The venture's root layout (EE-072, I-4): every route's layout chain starts here. Lines shaped
+// "key: value" are instructions the router hands an agent with the layout.
+writeFileSync(join(dir, "AGENTS.md"), `# AGENTS.md: ${id}
+
+The map of this venture for agents. Read it, then a route's layout, before writing anything here.
+
+## How to work here
+
+- List the routes with \`mentura routes\`. Read a route's \`layout\` and \`template\` before you write to it.
+- Write through the router (the CLI or the MCP server), not by editing files. Every write is checked against its schema and recorded in provenance.jsonl.
+- A write that fails closed comes back as a draft in \`_drafts/\`. A person accepts it with \`mentura accept\`.
+- Never read or send anything under \`_private/\` to a model.
+- A deeper AGENTS.md (for example \`marketing/AGENTS.md\`) adds to this one for the routes under it; the nearer one wins.
+
+## Instructions
+
+phase: ${venture.phase}
+voice: plain words, in the founder's own terms
+private: _private/
+`);
+// The product foundation (EE-059): Naive's own questions about products, asked first and failing
+// closed. Does a product exist already, what is the core product, which product is the flagship.
+// Each waits on the one before it; agents may not write product cards until the first is answered.
+const framework = { drafted_by: { kind: "framework", id: "naive" } };
+const productFoundation = [
+  { id: "product-exists", question: "Does a product already exist (in use, for sale, a prototype or a pilot), or is the venture still an idea?", decides: { record: "product", path: "products/" }, statement: "products",
+    options: ["Yes: one or more products exist", "Partly: a prototype or pilot exists", "No: it is still an idea"],
+    unlocks: [{ activity: "Write product cards for what exists or is planned", routes: ["purpose/product/*"] }] },
+  { id: "core-product", parent: "product-exists", question: "What is the core product: what anyone can claim from this venture, who it is promised to, what it must never deliver, and the competence that makes it deliverable?", decides: { record: "venture", path: "venture.json" },
+    unlocks: [{ activity: "Judge the products against the core (Product Anatomy)", routes: ["purpose/anatomy-input/*", "purpose/anatomy-answers"] }] },
+  { id: "flagship", parent: "core-product", question: "Which product is the flagship now: the one that best delivers the core promise?", decides: { record: "product", path: "products/" },
+    unlocks: [{ activity: "Plan how to validate the flagship", routes: ["purpose/validation/solution"] }] },
+];
+// The team question (EE-060): asked in Discovery, failing open, so validation never waits on it. A
+// founding team, or a founder looking for one, gets the founder-agreement kit beside validation.
+mkdirSync(join(dir, "decisions"), { recursive: true });
+writeFileSync(join(dir, "decisions/venture.team.decision.json"), JSON.stringify({ id: "founding-team", question: "Who is founding this venture: you alone, you with cofounders, or you looking for cofounders?",
+  decides: { record: "founder-agreement", path: "governance/founder-agreement.json" }, layer: "governance", boundary: "fail-open", needed_in: phase, status: "open",
+  options: ["Solo: I am founding it alone", "Cofounders: we are founding it together", "Looking: I want cofounders"],
+  unlocks: [{ activity: "Draft the founder agreement with the founding-agreement kit", routes: ["governance/founder-agreement"] }], provenance: framework }, null, 2) + "\n");
+mkdirSync(join(dir, "products/decisions"), { recursive: true });
+for (const d of productFoundation) writeFileSync(join(dir, "products/decisions", `product.${d.id.replace(/^product-/, "")}.decision.json`),
+  JSON.stringify({ ...d, layer: "purpose", boundary: "fail-closed", needed_in: phase, status: "open", provenance: framework }, null, 2) + "\n");
+console.log(`created venture ${id} (${phase}) in ${dir} with ${on.join(", ") || "no layers"}, products/, accounts/ and the three pillars.${venture.core ? " Fill in the core product before ranking products." : ""}`);