naive-framework 0.0.0-stage → 0.1.0

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)}`);
+}

package/schema/bdd.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Runs Gherkin feature files as tests (EE-050): behavior-driven development without dependencies.
+// Each scenario's Given, When, Then, And and But steps are matched against the step definitions
+// in <name>.steps.mjs beside <name>.feature (an exported array of [RegExp, async (world, ...groups)]).
+// A step with no definition fails its scenario, so a behavior cannot be written down and skipped.
+//
+//   node schema/bdd.mjs <file.feature>...
+//
+// Supports Feature, Rule, Background, Scenario, the five step keywords and # comments; not
+// Scenario Outline, tables or doc strings yet.
+
+import { readFileSync } from "node:fs";
+
+export function parse(text) {
+  const scenarios = [];
+  let rule = null, background = [], cur = null;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    let m;
+    if ((m = line.match(/^Rule:\s*(.*)$/))) { rule = m[1]; background = []; cur = null; }
+    else if (/^Background:/.test(line)) cur = { background: true, steps: background };
+    else if ((m = line.match(/^Scenario:\s*(.*)$/))) { cur = { name: m[1], rule, steps: [...background] }; scenarios.push(cur); }
+    else if ((m = line.match(/^(Given|When|Then|And|But)\s+(.*)$/)) && cur) cur.steps.push(m[2]);
+  }
+  return scenarios;
+}
+
+export async function run(file) {
+  const { steps } = await import(file.replace(/\.feature$/, ".steps.mjs").replace(/^(?!\/)/, `${process.cwd()}/`));
+  const results = [];
+  for (const sc of parse(readFileSync(file, "utf8"))) {
+    const world = {};
+    let error = null;
+    for (const text of sc.steps) {
+      const hit = steps.map(([re, fn]) => [text.match(re), fn]).find(([m]) => m);
+      if (!hit) { error = `no step definition: ${text}`; break; }
+      try { await hit[1](world, ...hit[0].slice(1)); } catch (e) { error = `${text}: ${e.message}`; break; }
+    }
+    await world.cleanup?.();
+    results.push({ scenario: sc.name, rule: sc.rule, ok: !error, error });
+  }
+  return results;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const files = process.argv.slice(2);
+  if (!files.length) { console.error("usage: node schema/bdd.mjs <file.feature>..."); process.exit(2); }
+  let failed = 0;
+  for (const f of files) for (const r of await run(f)) {
+    console.log(`${r.ok ? "ok  " : "FAIL"} ${r.scenario}${r.ok ? "" : `\n       ${r.error}`}`);
+    if (!r.ok) failed++;
+  }
+  console.log(failed ? `\n${failed} scenarios failing` : "\nall scenarios pass");
+  process.exit(failed ? 1 : 0);
+}

package/schema/board.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "board.schema.json",
+  "title": "Boards",
+  "description": "The venture's boards, at <venture>/governance/board.json (EE-022): at most one formal board of directors (or managers, or trustees), which holds legal authority, and any advisory boards, which advise and decide nothing. A seat says who fills it and who appoints them; reserved matters are what only the formal board may decide. schema/check-governance.mjs checks seats against ownership.json.",
+  "type": "object",
+  "required": [
+    "updated",
+    "boards"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "updated": {
+      "type": "string",
+      "format": "date"
+    },
+    "boards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind",
+          "seats"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "kind": {
+            "enum": [
+              "formal",
+              "advisory"
+            ]
+          },
+          "formed": {
+            "type": "string",
+            "format": "date"
+          },
+          "meets": {
+            "enum": [
+              "monthly",
+              "every-6-weeks",
+              "quarterly",
+              "twice-a-year",
+              "yearly",
+              "as-needed"
+            ]
+          },
+          "seats": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "type",
+                "appointed_by"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9-]+$"
+                },
+                "person": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "null while the seat is empty"
+                },
+                "type": {
+                  "enum": [
+                    "founder",
+                    "investor",
+                    "independent",
+                    "advisor",
+                    "observer"
+                  ]
+                },
+                "appointed_by": {
+                  "type": "string",
+                  "description": "A holder id, a class id from ownership.json, or 'board' (chosen by the board itself)"
+                }
+              }
+            }
+          },
+          "reserved_matters": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Formal boards only: decisions only this board may make, such as issuing shares, approving the budget, hiring or removing the CEO, selling the company"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/check-boundary.mjs

@@ -0,0 +1,54 @@
+// The framework/platform boundary (EE-041). Mentura is a framework (conventions that work offline,
+// with no account and no named vendor, like Next.js) and a platform that hosts, connects and
+// integrates (like Vercel). Both live in this repository; platform code lives in platform/.
+//
+//   1. Nothing outside platform/ imports from it. The platform builds on the framework, never the
+//      other way round. The framework may still load a platform connector by the module path the
+//      registry names (knowledge/tooling/integrations.json): that is inversion of control, like a
+//      Next.js adapter, and it never fails when the platform is absent from a copy.
+//   2. A connector the framework ships (its module outside platform/) works offline and names no
+//      vendor: no fetch, no node:http, node:https or node:net, and no credentials.
+//   3. Every registered connector module exists.
+//
+//   node schema/check-boundary.mjs        (EE_ROOT=<dir> checks another copy)
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const root = process.env.EE_ROOT ?? new URL("..", import.meta.url).pathname;
+const PLATFORM = "platform";
+const SKIP = /^(\.git|node_modules|\.next|_pagefind|out|generated)$/;
+const CODE = /\.(mjs|cjs|js|jsx|ts|tsx)$/;
+const errors = [];
+
+const walk = (d) => readdirSync(d, { withFileTypes: true }).flatMap((e) => SKIP.test(e.name) ? []
+  : e.isDirectory() ? walk(join(d, e.name)) : CODE.test(e.name) ? [join(d, e.name)] : []);
+const inPlatform = (abs) => { const r = relative(root, abs); return r === PLATFORM || r.startsWith(PLATFORM + "/"); };
+
+// 1. Imports: static, dynamic with a literal, and require.
+const SPEC = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)(["'`])([^"'`]+)\1/gm;
+let files = 0;
+for (const f of walk(root).filter((f) => !inPlatform(f))) {
+  files++;
+  const src = readFileSync(f, "utf8");
+  for (const m of src.matchAll(SPEC)) {
+    const spec = m[2];
+    const target = spec.startsWith(".") ? resolve(dirname(f), spec) : spec.startsWith("/") ? spec : null;
+    if (target && inPlatform(target)) errors.push(`${relative(root, f)} imports ${spec}: framework code never imports platform code`);
+  }
+}
+
+// 2 and 3. Connectors in the registry.
+const regFile = join(root, "knowledge/tooling/integrations.json");
+const reg = existsSync(regFile) ? JSON.parse(readFileSync(regFile, "utf8")).filter((t) => t.connector) : [];
+const NET = /\bfetch\s*\(|["']node:(https?|net|tls|dgram)["']/;
+for (const t of reg) {
+  const abs = join(root, t.connector.module);
+  if (!existsSync(abs)) { errors.push(`integration ${t.id}: connector module ${t.connector.module} does not exist`); continue; }
+  if (inPlatform(abs)) continue;
+  if (NET.test(readFileSync(abs, "utf8"))) errors.push(`integration ${t.id}: ${t.connector.module} reaches the network, so it belongs in ${PLATFORM}/`);
+  if (t.credentials?.length) errors.push(`integration ${t.id}: a framework connector needs no credentials (it names ${t.credentials.join(", ")}), so it belongs in ${PLATFORM}/`);
+}
+
+if (errors.length) { for (const e of errors) console.error(e); process.exit(1); }
+console.log(`${files} framework code files import nothing from ${PLATFORM}/; ${reg.filter((t) => !inPlatform(join(root, t.connector.module))).length} framework connector(s) work offline.`);