naive-framework 0.0.0-stage → 0.2.0

package/schema/account.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "account.schema.json",
+  "title": "Account",
+  "description": "One named party the venture keeps a record for, at accounts/<id>/account.json inside the venture that serves it (EE-011, EE-021). Optional: only ventures that work per party need accounts; who a product serves in general is its market. Account follows CRM usage (an organization or person you have a relationship with). Not a venture: it has no phase or core.",
+  "type": "object",
+  "required": [
+    "id",
+    "name",
+    "relationship",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string"
+    },
+    "relationship": {
+      "enum": [
+        "client",
+        "customer",
+        "user",
+        "member",
+        "partner",
+        "other"
+      ],
+      "description": "How the venture stands to this party (EE-021). client: served under a professional relationship; customer: buys; user: uses, may not pay; member: belongs (a club, community or cooperative); partner: works with the venture; other: say which in the note"
+    },
+    "status": {
+      "enum": [
+        "prospect",
+        "active",
+        "paused",
+        "closed"
+      ]
+    },
+    "opened": {
+      "type": "string",
+      "format": "date"
+    },
+    "closed": {
+      "type": "string",
+      "format": "date"
+    },
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Ids of the venture's products this account buys or uses"
+    },
+    "profile": {
+      "type": "string"
+    },
+    "layers": {
+      "type": "object",
+      "description": "Optional: where this account's knowledge and operations records live",
+      "properties": {
+        "knowledge": {
+          "$ref": "venture.schema.json#/$defs/layer"
+        },
+        "operations": {
+          "$ref": "venture.schema.json#/$defs/layer"
+        },
+        "evidence": {
+          "$ref": "venture.schema.json#/$defs/layer"
+        }
+      },
+      "additionalProperties": false
+    },
+    "note": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/schema/adapter.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adapter.schema.json",
+  "title": "Adapter",
+  "description": "What runs Naive on a platform or in an agent harness (Z-4), as a Next.js adapter customizes build and deploy for a platform. A harness adapter (Claude Code, Codex, Cursor) adapts the framework through the venture's AGENTS.md and skills: the entry files it writes into a venture, and where it puts the package skills. A platform adapter (Mentura, Naive's first, as Vercel is for Next.js) names the tests it runs. An adapter is verified when it passes the framework's tests (node interface/adapters.mjs verify <name>). Harness adapters are interface/adapters/<name>.json; the platform's is platform/adapter.json.",
+  "type": "object",
+  "required": ["name", "title", "kind", "reads", "files", "skills", "sources"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "title": { "type": "string" },
+    "kind": { "enum": ["harness", "platform"] },
+    "integration": { "type": "string", "description": "Its entry in interface/tooling/integrations.json" },
+    "reads": { "type": "array", "items": { "type": "string" }, "description": "The files the harness or platform reads on its own, as globs" },
+    "files": {
+      "type": "array",
+      "description": "Entry files the adapter writes into a venture; each must lead to the venture's AGENTS.md",
+      "items": {
+        "type": "object",
+        "required": ["path", "text"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "pattern": "^(?!/)(?!.*\\.\\.)(?!_private/).+$" },
+          "text": { "type": "string" }
+        }
+      }
+    },
+    "skills": { "type": ["string", "null"], "description": "The folder the harness loads skills from; each open package's skill is copied to <folder>/<skill id>/SKILL.md. null when the harness reaches skills through AGENTS.md" },
+    "verify": { "type": "array", "items": { "type": "string" }, "description": "A platform adapter: the test programs it must pass, each run as node <path> and ending with all passing or exit 0" },
+    "sources": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Where the harness documents what it reads" },
+    "note": { "type": "string" }
+  }
+}

package/schema/add-department.mjs

@@ -0,0 +1,41 @@
+// Imports one department into a venture (EE-047, EE-048): lists it in venture.json `departments`
+// and creates its folders, the operations side always and the governance side when the venture's
+// governance layer is on. Nothing else is created, so a venture holds only what it uses.
+//
+//   node schema/add-department.mjs <venture dir> <department id> [--group]
+//
+// --group puts the folders under primary/ or support/, by the department's place in the value
+// chain. The grouping is for looking at only: the department.json tag says what the folder is.
+// Writes nothing over an existing folder.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { catalog, foldersOf } from "./departments.mjs";
+
+const args = process.argv.slice(2);
+const group = args.includes("--group");
+const [dir, id] = args.filter((a) => !a.startsWith("--"));
+if (!dir || !id) { console.error("usage: node schema/add-department.mjs <venture dir> <department id> [--group]"); process.exit(2); }
+if (!existsSync(join(dir, "venture.json"))) { console.error(`${dir} has no venture.json`); process.exit(2); }
+const all = catalog();
+const d = all.find((x) => x.id === id);
+if (!d) { console.error(`unknown department ${id}: one of ${all.map((x) => x.id).join(", ")}`); process.exit(2); }
+
+const venture = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8"));
+const layersOn = ["operations", ...(venture.layers?.governance ? ["governance"] : [])];
+const held = foldersOf(dir).filter((f) => f.tag?.department === id).map((f) => f.layer);
+const tag = { department: d.id, value_chain: d.value_chain, apqc: d.apqc.id };
+const made = [];
+for (const layer of layersOn.filter((l) => !held.includes(l))) {
+  const rel = join(layer, "departments", ...(group ? [d.value_chain] : []), d.id);
+  if (existsSync(join(dir, rel))) { console.error(`${rel} exists without a department.json; add the tag by hand`); process.exit(1); }
+  mkdirSync(join(dir, rel), { recursive: true });
+  writeFileSync(join(dir, rel, "department.json"), JSON.stringify(tag, null, 2) + "\n");
+  const [file, title, what] = layer === "governance"
+    ? ["charter.md", "charter", d.governance] : ["README.md", "operations", d.operations];
+  writeFileSync(join(dir, rel, file), `# ${d.label}: ${title}\n\nHolds: ${what}.\n\nAPQC ${d.apqc.id} ${d.apqc.name}; value chain: ${d.value_chain} (${d.porter}).\n`);
+  made.push(rel);
+}
+venture.departments = [...new Set([...(venture.departments ?? []), d.id])];
+writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
+console.log(made.length ? `added ${d.label}: ${made.join(", ")}` : `${d.label} is already in ${dir}`);

package/schema/agent-capability.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agent-capability.schema.json",
+  "title": "Agent capability register",
+  "description": "What agents can and cannot do, task by task, with sources and dates (EE-029), at evidence/capabilities/agent-capabilities.json. Team plans cite these entries: a task an agent cannot do, may not do, or is not known to do needs a named human loop. Kept current by reading new research and by our own evals.",
+  "type": "object",
+  "required": [
+    "updated",
+    "capabilities"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "note": {
+      "type": "string"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "task",
+          "status",
+          "basis",
+          "checked"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "task": {
+            "type": "string"
+          },
+          "area": {
+            "type": "string",
+            "description": "The layer or MAD tier the task belongs to"
+          },
+          "status": {
+            "enum": [
+              "can",
+              "can-with-review",
+              "cannot",
+              "not-allowed",
+              "unknown"
+            ],
+            "description": "can: no human loop needed; can-with-review: an agent does it and a person or a check reviews it; cannot: beyond agents today; not-allowed: agents may be able, but decision rights or law reserve it to a person; unknown: no evidence yet, so a human loop by default and an eval to find out"
+          },
+          "basis": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "minProperties": 1,
+              "properties": {
+                "title": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string",
+                  "format": "uri"
+                },
+                "checked": {
+                  "type": "string",
+                  "format": "date"
+                },
+                "eval": {
+                  "type": "string",
+                  "description": "A result file of our own eval, relative to the repository"
+                },
+                "decision_class": {
+                  "type": "string",
+                  "description": "For not-allowed: the decision class that reserves it"
+                }
+              }
+            }
+          },
+          "checked": {
+            "type": "string",
+            "format": "date"
+          },
+          "notes": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/alignment.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "alignment.schema.json",
+  "title": "Alignment",
+  "description": "How the venture's products and agents must behave (EE-053): a list of principles, each with its source and the check that holds it, at <venture>/purpose/alignment.json. A foundation statement, gated: an agent's change is a draft the founder accepts.",
+  "type": "object",
+  "required": [
+    "venture",
+    "principles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "venture": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "principles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "statement",
+          "source"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "statement": {
+            "type": "string",
+            "description": "What must always or never happen, in the founder's words"
+          },
+          "applies_to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Product ids, or agents or team, that the principle binds"
+          },
+          "source": {
+            "type": "string",
+            "description": "Who or what it comes from: the founder's words with a date, a decision id or a reference"
+          },
+          "check": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The test or script that holds it, or null when nothing checks it yet"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/assess-problem.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Assesses a venture's problem from its evidence (EE-050), the lean validation suite. No single
+// score: the problem splits into four assumptions, each labelled from its evidence, and the
+// labels say which commitment the evidence is strong enough for. Behaviors it must keep are in
+// purpose/kits/validation/features/problem-assessment.feature.
+//
+//   node schema/assess-problem.mjs <venture dir> [--json] [--preflight] [--as-is]
+//
+// Assumptions: exists (the problem is real), segment (our segment has it), hurts (it costs
+//   enough that people already spend time or money on it), why-now (something has changed).
+// Labels: demonstrated, inferred, assumed, unknown, contradicted.
+//   An item demonstrates when it is behavior or commitment from the target segment, first-hand
+//   (a file in the venture folder, or origin first-hand), five or more people, under 18 months
+//   old. Any other item from a target, adjacent or unknown audience infers; the wrong audience
+//   counts for nothing. Competitors with paying customers are behavior from an adjacent audience:
+//   they infer the problem, never count against it.
+//   Contradicted needs evidence against from the target segment at least as strong as the best
+//   evidence for. Missing evidence is unknown, never a verdict.
+// Ladder: explore, prototype, charge, raise. The result names the rung the evidence supports and
+//   the cheapest test for each assumption that blocks the next rung. It never says "not viable".
+// Forms: a root problem may take several forms (forms[]), each with its own evidence (evidence
+//   form); each open form is labelled from its own items, which also count for the root.
+// Preflight: before assessing, it lists what is missing from the record and what running as is
+//   would mean, and stops with needs_input unless --as-is is given. The router, CLI, MCP server
+//   and API pass the same choice on (input as_is).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const ASSUMPTIONS = [
+  { id: "exists", says: "the problem is real", field: "statement", test: "Find people already paying for or building a workaround (search, forums, competitors' customers)" },
+  { id: "segment", says: "our segment has it", field: "segment", test: "Five problem interviews with people in the segment, asking about the last time it happened" },
+  { id: "hurts", says: "it costs enough that people already spend time or money on it", field: "cost or workarounds", test: "Ask in those interviews what they spent on it last month, in hours or money, and look for a workaround they pay for" },
+  { id: "why-now", says: "something has changed that makes it solvable or urgent now", field: "why_now", test: "Cite the change: a trend, a new technology, a rule, with a source" },
+];
+export const LADDER = [
+  { rung: "explore", unlocks: "keep researching the problem" },
+  { rung: "prototype", unlocks: "build something cheap to test a solution", needs: { exists: 1, hurts: 1 } },
+  { rung: "charge", unlocks: "ask people in the segment to pay", needs: { exists: 1, segment: 2, hurts: 2 } },
+  { rung: "raise", unlocks: "ask investors for money on the problem's strength (the problem alone is never enough)", needs: { exists: 2, segment: 2, hurts: 2, "why-now": 1 } },
+];
+const LABEL = { 2: "demonstrated", 1: "inferred" };
+const MIN_SAMPLE = 5, MAX_AGE_MONTHS = 18;
+
+const months = (from, to) => (to - new Date(from)) / (1000 * 60 * 60 * 24 * 30.44);
+export const originOf = (e) => e.origin ?? (e.source?.path && !e.source?.url ? "first-hand" : "reported");
+
+/** How strongly one item bears on its assumption: 2 demonstrates, 1 infers, 0 counts for nothing. */
+export function strength(e, today = new Date()) {
+  if (e.audience === "wrong") return 0;
+  const shows = ["behavior", "commitment"].includes(e.kind) && e.audience === "target" && originOf(e) === "first-hand"
+    && (e.sample?.n ?? 0) >= MIN_SAMPLE && months(e.collected, today) <= MAX_AGE_MONTHS;
+  return shows ? 2 : 1;
+}
+
+const stated = (rec, a) => a.id === "hurts" ? !!(rec.cost || rec.workarounds?.length) : a.id === "why-now" ? !!rec.why_now : !!rec[a.field];
+
+/** The label for each assumption, with the items behind it. */
+export function label(rec, today = new Date()) {
+  const ev = rec?.evidence ?? [];
+  return ASSUMPTIONS.map((a) => {
+    const on = ev.filter((e) => (e.assumption ?? "exists") === a.id).map((e) => ({ id: e.id, supports: e.supports !== false, s: strength(e, today), target: e.audience === "target" }));
+    const best = Math.max(0, ...on.filter((x) => x.supports).map((x) => x.s));
+    const against = Math.max(0, ...on.filter((x) => !x.supports && x.target).map((x) => x.s));
+    const level = against > 0 && against >= best ? 0 : best;
+    const name = against > 0 && against >= best ? "contradicted" : LABEL[best] ?? (rec && stated(rec, a) ? "assumed" : "unknown");
+    return { assumption: a.id, says: a.says, label: name, level, for: on.filter((x) => x.supports && x.s > 0).map((x) => x.id), against: on.filter((x) => !x.supports).map((x) => x.id), ignored: on.filter((x) => x.s === 0).map((x) => x.id) };
+  });
+}
+
+/** The highest rung the labels support, and what blocks the next one. */
+export function ladder(labels) {
+  const lv = Object.fromEntries(labels.map((l) => [l.assumption, l.level]));
+  const contradicted = labels.filter((l) => l.label === "contradicted").map((l) => l.assumption);
+  let i = 0;
+  while (i + 1 < LADDER.length && !contradicted.length && Object.entries(LADDER[i + 1].needs).every(([a, n]) => lv[a] >= n)) i++;
+  const next = LADDER[i + 1];
+  const blocking = next ? Object.entries(next.needs).filter(([a, n]) => lv[a] < n || contradicted.includes(a)).map(([a, n]) => ({ assumption: a, needs: LABEL[n], has: labels.find((l) => l.assumption === a).label, test: ASSUMPTIONS.find((x) => x.id === a).test })) : [];
+  return { supports: LADDER[i].rung, unlocks: LADDER[i].unlocks, next: next?.rung ?? null, blocking, contradicted };
+}
+
+/** What is missing from the record before assessing it, and what running as is would mean. */
+export function preflight(rec) {
+  if (!rec) return [{ field: "purpose/validation/problem.json", why: "there is no problem record", as_is: "every assumption is unknown; the evidence supports exploring only" }];
+  const m = [];
+  for (const a of ASSUMPTIONS) if (!stated(rec, a)) m.push({ field: a.field, why: `says whether ${a.says}`, as_is: `${a.id} is unknown unless evidence bears on it` });
+  const untagged = (rec.evidence ?? []).filter((e) => !e.assumption).map((e) => e.id);
+  if (untagged.length) m.push({ field: "evidence[].assumption", items: untagged, why: "which assumption each item bears on (exists, segment, hurts, why-now)", as_is: "these items count toward exists only" });
+  const thin = (rec.evidence ?? []).filter((e) => ["behavior", "commitment", "stated"].includes(e.kind) && !e.sample).map((e) => e.id);
+  if (thin.length) m.push({ field: "evidence[].sample", items: thin, why: "how many people the item comes from", as_is: "these items can infer but not demonstrate" });
+  const bare = ASSUMPTIONS.filter((a) => !(rec.evidence ?? []).some((e) => (e.assumption ?? "exists") === a.id)).map((a) => a.id);
+  if (bare.length) m.push({ field: "evidence", items: bare, why: "no evidence bears on these assumptions yet", as_is: "they stay assumed or unknown" });
+  return m;
+}
+
+export const ASK = "Some things the assessment reads are missing. Fill them in first, or run it as is?";
+
+/** The whole run: preflight first, then the assessment unless input is missing and as_is is not set. */
+export function assess(dir, { as_is = false, today = new Date() } = {}) {
+  const f = join(dir, "purpose/validation/problem.json");
+  const rec = existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
+  const missing = preflight(rec);
+  if (missing.length && !as_is) return { needs_input: { ask: ASK, missing, options: [
+    { choice: "fill-in", how: "write the missing fields to purpose/validation/problem.json (template: purpose/kits/validation/templates/problem.md), then run again" },
+    { choice: "run-as-is", how: "run again with as_is (CLI --as-is; MCP and API as_is: true)" }] } };
+  const labels = label(rec, today);
+  // Each open form is assessed from its own evidence; its evidence also counts for the root.
+  const forms = (rec?.forms ?? []).filter((f) => f.status !== "dropped").map((f) => {
+    const own = label({ ...rec, statement: f.statement, segment: f.segment ?? rec.segment, evidence: (rec.evidence ?? []).filter((e) => e.form === f.id) }, today);
+    const { supports, next, blocking } = ladder(own);
+    return { form: f.id, statement: f.statement, assumptions: own, supports, next, blocking };
+  });
+  return { venture: rec?.venture ?? null, ran_as_is: missing.length > 0, missing, assumptions: labels, ...ladder(labels), forms };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir) { console.error("usage: node schema/assess-problem.mjs <venture dir> [--json] [--preflight] [--as-is]"); process.exit(2); }
+  const flag = (f) => process.argv.includes(f);
+  const out = flag("--preflight") ? { missing: preflight(existsSync(join(dir, "purpose/validation/problem.json")) ? JSON.parse(readFileSync(join(dir, "purpose/validation/problem.json"), "utf8")) : null) } : assess(dir, { as_is: flag("--as-is") });
+  if (flag("--json")) { console.log(JSON.stringify(out, null, 2)); process.exit(0); }
+  const list = (m) => m.map((x) => `  - ${x.field}${x.items ? ` (${x.items.join(", ")})` : ""}: ${x.why}. As is: ${x.as_is}`).join("\n");
+  if (out.needs_input) { console.log(`${out.needs_input.ask}\n${list(out.needs_input.missing)}\nFill in: ${out.needs_input.options[0].how}\nRun as is: ${out.needs_input.options[1].how}`); process.exit(0); }
+  if (!out.assumptions) { console.log(out.missing.length ? list(out.missing) : "nothing missing"); process.exit(0); }
+  for (const a of out.assumptions) console.log(`${a.assumption.padEnd(8)} ${a.label.padEnd(13)} ${a.says}${a.for.length ? `  [for: ${a.for.join(", ")}]` : ""}${a.against.length ? `  [against: ${a.against.join(", ")}]` : ""}`);
+  console.log(`\nThe evidence supports: ${out.supports} (${out.unlocks}).`);
+  if (out.contradicted.length) console.log(`Evidence from the segment contradicts ${out.contradicted.join(", ")}: reframe the problem or the segment and test again.`);
+  if (out.next) console.log(`To reach ${out.next}:\n${out.blocking.map((b) => `  - ${b.assumption}: ${b.has}, needs ${b.needs}. ${b.test}`).join("\n")}`);
+  for (const f of out.forms) console.log(`\nForm ${f.form}: supports ${f.supports}. ${f.assumptions.map((a) => `${a.assumption} ${a.label}`).join(", ")}`);
+  if (out.ran_as_is) console.log(`\nRan as is; missing:\n${list(out.missing)}`);
+}