naive-framework 0.0.0-stage → 0.1.0

package/packages/validation/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "validation",
+  "title": "Validation",
+  "kind": "core",
+  "purpose": "Whether the problem is real, whether this solves it, whether people pay and keep using it, with the evidence graded.",
+  "department": "strategy",
+  "required": [
+    "validation-solution",
+    "validation-pricing",
+    "validation-go-to-market"
+  ],
+  "optional": [
+    "validation-product-market-fit",
+    "evidence"
+  ],
+  "refs": [
+    "validation-problem",
+    "icp"
+  ],
+  "planned": [
+    "customer feedback"
+  ],
+  "base": {
+    "discovery": 0.6,
+    "validation": 0.95,
+    "beachhead": 0.6,
+    "scale": 0.3,
+    "platform": 0.2
+  },
+  "when": [
+    {
+      "if": "ambition:hobby",
+      "at_most": 0.4
+    }
+  ],
+  "why": "The work of Discovery and Validation; it fades once retention holds",
+  "unlocks": [
+    "interview scheduling",
+    "surveys",
+    "research runs"
+  ],
+  "gates": [
+    "a person has confirmed every required record and every record this package reads"
+  ],
+  "schemas": [
+    "schema/validation-problem.schema.json",
+    "schema/validation-solution.schema.json",
+    "schema/validation-product-market-fit.schema.json",
+    "schema/validation-pricing.schema.json",
+    "schema/validation-go-to-market.schema.json",
+    "schema/validation-team.schema.json",
+    "schema/validation-operations-readiness.schema.json",
+    "schema/evidence.schema.json"
+  ],
+  "templates": [
+    "purpose/kits/validation/templates/go-to-market.md",
+    "purpose/kits/validation/templates/operations-readiness.md",
+    "purpose/kits/validation/templates/pricing.md",
+    "purpose/kits/validation/templates/problem-interview.md",
+    "purpose/kits/validation/templates/problem.md",
+    "purpose/kits/validation/templates/product-market-fit.md",
+    "purpose/kits/validation/templates/solution.md",
+    "purpose/kits/validation/templates/team.md"
+  ],
+  "checks": [
+    "schema/check-validation.mjs",
+    "schema/assess-problem.mjs",
+    "schema/bdd.mjs"
+  ],
+  "skill": {
+    "id": "problem-validation",
+    "path": "purpose/kits/validation/skills/problem-validation/SKILL.md"
+  },
+  "use_model": [],
+  "layer": "purpose",
+  "records": [
+    "validation-problem",
+    "validation-solution",
+    "validation-product-market-fit",
+    "validation-pricing",
+    "validation-go-to-market",
+    "validation-team",
+    "validation-operations-readiness",
+    "validation-weights"
+  ],
+  "reads": [
+    "venture",
+    "product"
+  ],
+  "writes": [],
+  "template_dir": "purpose/kits/validation/templates",
+  "references": "purpose/kits/validation/references/references.json",
+  "gaps": [
+    "Jev does not score the probability yet; the example uses an owner value",
+    "Validation weights and floors are ours and unevaluated (version 0.x)",
+    "The single validation score (validation-score skill, purpose/validation/score) is held, not removed: EE-050 replaces it for the problem; the other sub-scores are not yet assessed the new way"
+  ],
+  "absorbed": "purpose/kits/validation/kit.json (EE-071). The held validation-score skill stays on the purpose layer."
+}

package/platform/README.md

@@ -0,0 +1,45 @@
+---
+type: reference
+source: hybrid
+created: 2026-10-28T03:07:56Z
+ai-model: claude-opus-5.5
+tags: [everything-ecosystem, mentura, platform, framework, boundary]
+description: "The platform side of Mentura: what lives here, the boundary with the framework, and how it is enforced (EE-041)."
+---
+
+# Platform
+
+The system has two sides, the way Next.js and Vercel do (EE-041): the framework Naive and the platform Mentura.
+
+- **The framework**, Naive (EE-043), is the conventions. It works offline, with no account, and names no vendor. It covers record schemas and the data model, kits, the router and the CLI, MCP server and local API over it, routes, provenance, the checks, need-now priors, validation scoring, `init-venture`, the connector contract with the filesystem connector, and the docs. That is everything in this repository outside `platform/`.
+- **The platform** hosts, connects and integrates. It holds connectors that reach a vendor over the network with credentials, the connect flow, integrations that call outside services (analytics, Listen Labs, Jev routing, treg), a hosted catalog and search, the operator console, and a gallery of templates. That is this folder.
+
+A template is framework, the way `create-next-app --example` is. The gallery that hosts templates is platform.
+
+## The boundary
+
+The platform builds on the framework, and never the other way round. `node schema/check-boundary.mjs` (run by `node test.mjs`) fails when:
+
+1. a file outside `platform/` imports anything from `platform/`;
+2. a connector registered outside `platform/` reaches the network or names credentials;
+3. a registered connector module does not exist.
+
+The framework can still load a platform connector by the module path in `knowledge/tooling/integrations.json`. That is inversion of control, like a Next.js deployment adapter: the framework defines the contract, and the platform implements it for a vendor.
+
+## What is here
+
+| Path | Holds |
+|---|---|
+| `connectors/github.mjs` | The GitHub connector: reads from a branch, writes by draft pull request (EE-037) |
+| `connectors/fake-github.mjs` | A fake of the GitHub REST API for offline evals |
+| `connectors/eval.mjs` | The GitHub connector against the framework's contract suite (`knowledge/connectors/suite.mjs`), the router over a GitHub source, the catalog, and an optional live run |
+| `mcp/research.mjs` | Market research for agents through Firecrawl, as an MCP server: search and read a page, every result with its URL (EE-059). Needs `FIRECRAWL_API_KEY` |
+| `integrations/jev.mjs` | Jev (TypeSafe) for typed judgments: sends a request the framework built, such as the idea map's tags, and prints the answers (EE-059). Needs `TYPESAFE_API_KEY` |
+| `integrations/langsmith.mjs` | Uploads a harness run's trace, with Naive's evals as feedback, to LangSmith (EE-059). Needs `LANGSMITH_API_KEY` |
+| `integrations/langsmith-docket.mjs` | The docket's evidence as a LangSmith experiment: the scenario states as a dataset, and one scored run of the docket and the judge (Jev) as an experiment over it (EE-075). Needs `LANGSMITH_API_KEY` |
+| `integrations/rho.mjs` | Rho, the founder's bank and spend suite, as the venture's money source: syncs `money/` (accounts, a sensitive append-only transactions stream, and a summary) over Rho's MCP server, calling only read-only tools (EE-070). Rho's sandbox by default; `--live` needs `RHO_API_TOKEN` |
+| `integrations/site.mjs` | Reads a venture's website: the home page and the pages it links to, as text, with where each sits (EE-062). Uses `FIRECRAWL_API_KEY` when set, a plain fetch otherwise |
+
+## Not yet moved
+
+Each layer's `tooling/integrations.json` stays in the framework for now. Most entries are opinionated defaults with references (EE-014), plain data that calls nothing, like a framework's docs recommending a host. An entry moves here once it carries code that calls a vendor.

package/platform/connectors/eval.mjs

@@ -0,0 +1,154 @@
+// Evals for the platform's GitHub connector (EE-037, EE-041). The GitHub connector names a vendor
+// and reaches it over the network, so it is platform, not framework; it proves itself against the
+// framework's contract suite (knowledge/connectors/suite.mjs). Three parts:
+//
+//   contract   the shared suite, run against a fake of the GitHub API, plus GitHub's own cases
+//   router     a venture whose source map keeps one record type in a GitHub repository: reads
+//              come from there with their version, a write opens a draft pull request and is
+//              logged with the source's version, nothing invalid reaches the source, and every
+//              other record stays in the venture folder
+//   catalog    one index across both sources, rebuilt after the pull request is merged
+//
+//   node platform/connectors/eval.mjs
+//
+// Live GitHub: with MENTURA_EVAL_GITHUB_REPO=owner/name (and a token in GITHUB_TOKEN, or the
+// variable MENTURA_EVAL_GITHUB_TOKEN names), the read half of the contract also runs against that
+// repository (MENTURA_EVAL_GITHUB_REF, MENTURA_EVAL_GITHUB_ROOT narrow it), and with
+// MENTURA_EVAL_GITHUB_WRITE=1 it opens one real draft pull request. Without them it says it skipped.
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { blobSha } from "../../knowledge/connectors/contract.mjs";
+import { contract, FIXTURE, harness, OUTSIDE } from "../../knowledge/connectors/suite.mjs";
+import { useFetch } from "../../knowledge/connectors/index.mjs";
+import { build, FILE, load, search } from "../../knowledge/connectors/catalog.mjs";
+import { fakeGitHub } from "./fake-github.mjs";
+import { connect as ghConnect } from "./github.mjs";
+
+const repo = new URL("../..", import.meta.url).pathname;
+const h = harness("platform-connectors");
+const { expect, throws, skip, write, scratch, finish } = h;
+
+// The GitHub connector, against the fake.
+const ghMake = async ({ writes = "pull-request", search = "api" } = {}) => {
+  const gh = fakeGitHub({ repo: "acme/knowledge", files: { ...Object.fromEntries(Object.entries(FIXTURE).map(([p, c]) => [`kb/${p}`, c])), ...OUTSIDE } });
+  return { gh, c: ghConnect({ id: "acme", repo: "acme/knowledge", root: "kb", writes, search, token: "MENTURA_EVAL_FAKE_TOKEN", fetch: gh.fetch }),
+    base: (p) => gh.files()[`kb/${p}`] ?? null, later: (p, branch) => gh.files(branch)[`kb/${p}`] ?? null, pulls: () => gh.pulls };
+};
+process.env.MENTURA_EVAL_FAKE_TOKEN = "fake";
+const ghT = await contract(h, "github (fake API)", ghMake);
+{
+  const a = await ghT.c.read("notes/alpha.md");
+  expect("github (fake API): read gives the branch's commit and a permalink to the file at that commit", /^[0-9a-f]{40}$/.test(a.commit) && a.permalink === `https://github.com/acme/knowledge/blob/${a.commit}/kb/notes/alpha.md`);
+  expect("github (fake API): a pull request targets the source's branch and says merging accepts it", ghT.gh.pulls.every((p) => p.base.ref === "main" && /Merging this pull request accepts the write/.test(p.body)));
+  const scan = await ghMake({ search: "scan" });
+  expect("github (fake API): search by scanning finds the same items as code search", JSON.stringify((await scan.c.search("kettle pilot")).map((x) => x.path)) === JSON.stringify(["notes/alpha.md"]));
+  delete process.env.MENTURA_EVAL_FAKE_TOKEN;
+  expect("github (fake API): without a token it fails and names the variable to set", await throws(() => ghT.c.list(), /no valid token in MENTURA_EVAL_FAKE_TOKEN/));
+  process.env.MENTURA_EVAL_FAKE_TOKEN = "fake";
+  expect("github: a source with no repo, or that asks to write directly, is refused", await throws(() => ghConnect({ repo: "nope" })) && await throws(() => ghConnect({ repo: "a/b", writes: "direct" })));
+}
+
+// ---- Router --------------------------------------------------------------------------------------
+console.log("\n# router over a mapped source");
+const ws = join(scratch, "workspace");
+cpSync(join(repo, "schema/examples/workspace"), ws, { recursive: true });
+process.env.MENTURA_WORKSPACE = ws;
+const tandem = join(ws, "ventures/tandem");
+const { call } = await import("../../interface/router.mjs");
+const { entries } = await import("../../interface/provenance.mjs");
+const kettle = { ...Object.values((await call({ venture: "tandem", route: "purpose/product", action: "read" })).result)[0], id: "kettle", name: "Kettle (in GitHub)" };
+const team = fakeGitHub({ repo: "acme/tandem", files: { "ventures/tandem/products/kettle.json": JSON.stringify(kettle, null, 2) + "\n", "ventures/tandem/notes/launch.md": "# Launch plan\n\nShip the kettle subscription in spring.\n" } });
+useFetch(team.fetch);
+process.env.MENTURA_EVAL_FAKE_TOKEN = "fake";
+const map = { sources: [{ id: "team-repo", connector: "github", repo: "acme/tandem", ref: "main", root: "ventures/tandem", token: "MENTURA_EVAL_FAKE_TOKEN" }], records: { product: "team-repo" } };
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+const localProducts = existsSync(join(tandem, "products")) ? spawnSync("ls", [join(tandem, "products")], { encoding: "utf8" }).stdout.trim().split("\n") : [];
+
+const list = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a mapped record type is read from its source, not the venture folder", list.ok && JSON.stringify(Object.keys(list.result)) === JSON.stringify(["kettle"]) && localProducts.length > 0, JSON.stringify(list).slice(0, 300));
+const one = await call({ venture: "tandem", route: "purpose/product/kettle", action: "read" });
+expect("router: a read says which source and version it came from, with a permalink to cite", one.result?.name === "Kettle (in GitHub)" && one.source?.address === "team-repo://products/kettle.json"
+  && one.source.version === blobSha(JSON.stringify(kettle, null, 2) + "\n") && /github\.com\/acme\/tandem\/blob\/[0-9a-f]{40}\/ventures\/tandem\/products\/kettle\.json$/.test(one.source.permalink ?? ""), JSON.stringify(one.source));
+const local = await call({ venture: "tandem", route: "purpose/validation/problem", action: "read" });
+expect("router: every record type the map does not name stays in the venture folder", local.ok && local.source?.source === "venture" && local.source.version === blobSha(readFileSync(join(tandem, "purpose/validation/problem.json"))));
+const teapot = { ...kettle, id: "teapot", name: "Teapot" };
+const puts = () => team.calls.filter((x) => x.startsWith("PUT")).length;
+const before = puts();
+const bad = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: { id: "teapot" } });
+expect("router: a write that does not match the schema never reaches the source", !bad.ok && /does not match/.test(bad.error) && puts() === before);
+const w = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person", via: "cli", provenance: { derived_from: [one.source.permalink], note: "add the teapot" } });
+expect("router: a write to a pull-request source opens a draft pull request, for a person as for an agent", w.ok && w.result.draft === true && /^https:\/\/github\.com\/acme\/tandem\/pull\/1$/.test(w.result.pull_request ?? "") && team.pulls[0]?.draft === true, JSON.stringify(w));
+expect("router: nothing lands in the venture folder or on the source's branch until the pull request is merged",
+  !existsSync(join(tandem, "products/teapot.json")) && !team.files()["ventures/tandem/products/teapot.json"] && JSON.parse(team.files(team.pulls[0].head.ref)["ventures/tandem/products/teapot.json"]).name === "Teapot");
+const e = entries(tandem).at(-1);
+expect("router: the write is logged by address, with the source's version and the pull request",
+  e.entity === "team-repo://products/teapot.json" && e.activity === "draft" && e.source?.version === w.result.version && e.source.pull_request === w.result.pull_request && e.source.connector === "github" && e.derived_from?.[0] === one.source.permalink, JSON.stringify(e));
+const pending = await call({ venture: "tandem", route: "purpose/product/teapot", action: "read" });
+expect("router: reading it before the merge says a pull request is waiting", pending.result === null && pending.pending_pull_requests?.[0]?.pull_request === w.result.pull_request);
+const prov = spawnSync("node", [join(repo, "schema/check-provenance.mjs"), ws], { encoding: "utf8" });
+const srcCheck = (d) => spawnSync("node", [join(repo, "schema/check-sources.mjs"), d], { encoding: "utf8" });
+expect("router: check-provenance accepts entries for records in another source", prov.status === 0, prov.stderr);
+expect("router: check-sources accepts the map", srcCheck(ws).status === 0, srcCheck(ws).stderr);
+const valid = spawnSync("python3", ["-I", join(repo, "schema/validate.py"), "--schema", "knowledge-sources.schema.json", "--file", join(tandem, "knowledge/sources.json")], { encoding: "utf8" });
+expect("router: the map matches its schema", valid.status === 0, valid.stdout + valid.stderr);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ sources: [{ id: "team-repo", connector: "notion" }], records: { product: "team-repo", venture: "team-repo" } }) });
+const broken = srcCheck(ws);
+expect("router: check-sources refuses an unknown connector and a record type that must stay in the folder", broken.status === 1 && /no connector notion/.test(broken.stderr) && /venture stays in the venture folder/.test(broken.stderr), broken.stderr);
+const refused = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a read through an unknown connector fails and says which connectors exist", !refused.ok && /no connector notion: .*filesystem/.test(refused.error), refused.error);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...map, sources: [{ ...map.sources[0], writes: "none" }] }) });
+const ro = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person" });
+expect("router: a write to a read-only source is refused", !ro.ok && /read-only/.test(ro.error));
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+
+// ---- Catalog -------------------------------------------------------------------------------------
+console.log("\n# catalog");
+const { stats } = await build(tandem);
+const cat = load(tandem);
+expect("catalog: indexes every item in both sources", cat.items.some((x) => x.source === "team-repo" && x.path === "notes/launch.md") && cat.items.some((x) => x.source === "venture" && x.path === "purpose/validation/problem.json") && stats.errors.length === 0, JSON.stringify(stats));
+expect("catalog: every item has an address and its version", cat.items.every((x) => x.address === `${x.source}://${x.path}` && /^[0-9a-f]{40}$/.test(x.version)));
+expect("catalog: records are tied to their routes, wherever they live", cat.items.find((x) => x.address === "team-repo://products/kettle.json")?.route === "product/kettle" && cat.items.find((x) => x.path === "purpose/validation/problem.json")?.route === "foundation/problem");
+const s1 = search(cat, "kettle subscription spring");
+expect("catalog: search finds an item in the GitHub source", s1[0]?.address === "team-repo://notes/launch.md" && s1[0].title === "Launch plan", JSON.stringify(s1.slice(0, 2)));
+const research = readFileSync(join(tandem, "knowledge/research/pilot-2026-10.md"), "utf8");
+const s2 = search(cat, "pilot");
+expect("catalog: search finds an item in the venture folder", s2.some((x) => x.address === "venture://knowledge/research/pilot-2026-10.md"));
+const raw = readFileSync(join(tandem, FILE), "utf8");
+const phrase = research.split("\n").find((l) => l.split(" ").length > 6)?.slice(0, 40);
+expect("catalog: keeps no content (no sentence of an item appears in it)", phrase && !raw.includes(phrase) && !raw.includes("Ship the kettle subscription"), phrase);
+const again = (await build(tandem)).stats;
+expect("catalog: a rebuild with nothing changed reads nothing", again.read === 0 && again.reused === stats.items, JSON.stringify(again));
+team.branches.set("main", team.branches.get(team.pulls[0].head.ref)); // the pull request is merged
+const merged = (await build(tandem)).stats;
+expect("catalog: after the merge, a rebuild reads only the new item", merged.read === 1 && load(tandem).items.some((x) => x.address === "team-repo://products/teapot.json"), JSON.stringify(merged));
+expect("router: after the merge the record reads from the source", (await call({ venture: "tandem", route: "purpose/product/teapot", action: "read" })).result?.name === "Teapot");
+useFetch(null);
+
+// ---- Live GitHub (optional) ------------------------------------------------------------------------
+console.log("\n# live github");
+const live = process.env.MENTURA_EVAL_GITHUB_REPO;
+const tokenVar = process.env.MENTURA_EVAL_GITHUB_TOKEN ?? "GITHUB_TOKEN";
+if (!live || !process.env[tokenVar]) {
+  skip(`live GitHub: set MENTURA_EVAL_GITHUB_REPO=owner/name and a token in ${tokenVar} to run it`);
+} else {
+  const c = ghConnect({ id: "live", repo: live, ref: process.env.MENTURA_EVAL_GITHUB_REF ?? "main", root: process.env.MENTURA_EVAL_GITHUB_ROOT ?? "", token: tokenVar });
+  try {
+    const items = await c.list();
+    expect(`live github: lists ${live}`, items.length > 0);
+    const first = items.find((x) => /\.(md|json|txt)$/.test(x.path)) ?? items[0];
+    const r = await c.read(first.path);
+    expect("live github: read gives content whose git blob SHA-1 is the version GitHub reports", r && blobSha(r.content) === r.version && r.version === first.version);
+    expect("live github: read gives a permalink at a commit", /\/blob\/[0-9a-f]{40}\//.test(r.permalink ?? ""));
+    const word = r.content.split(/[^A-Za-z]+/).find((x) => x.length > 6);
+    if (word) { const hits = await c.search(word); expect(`live github: search for "${word}" returns items with versions`, hits.every((x) => /^[0-9a-f]{40}$/.test(x.version))); }
+    if (process.env.MENTURA_EVAL_GITHUB_WRITE === "1") {
+      const w = await c.write(`mentura-eval/${Date.now()}.md`, "# Mentura eval\n\nSafe to close.\n", { message: "Mentura connector eval (safe to close)" });
+      expect("live github: a write opens a draft pull request", /\/pull\/\d+$/.test(w.pull_request?.url ?? ""), JSON.stringify(w));
+      console.log(`     opened ${w.pull_request?.url}; close it and delete branch ${w.pull_request?.branch}`);
+    }
+  } catch (err) { expect("live github: reachable", false, err.message); }
+}
+
+finish();

package/platform/connectors/fake-github.mjs

@@ -0,0 +1,91 @@
+// A fake of the part of GitHub's REST API the GitHub connector uses, as a fetch function, so the
+// connector's evals run offline. It follows the real API's shapes and refusals: trees, contents
+// (404 for a missing file, 422 for a PUT over an existing file without its sha), commits, refs,
+// pulls and code search (default branch only), and 401 without a token. It is a test double, not a
+// second implementation: the live eval (MENTURA_EVAL_GITHUB_REPO) checks the same contract on the
+// real API.
+//
+//   const gh = fakeGitHub({ repo: "acme/knowledge", files: { "docs/a.md": "..." } });
+//   connect({ repo: "acme/knowledge", fetch: gh.fetch })
+
+import { createHash } from "node:crypto";
+import { blobSha, matches } from "../../knowledge/connectors/contract.mjs";
+
+export function fakeGitHub({ repo, files = {}, branch = "main", token = true } = {}) {
+  let n = 0;
+  const commits = new Map();
+  const commit = (snapshot) => { const sha = createHash("sha1").update(`commit ${++n}`).digest("hex"); commits.set(sha, new Map(snapshot)); return sha; };
+  const branches = new Map([[branch, commit(Object.entries(files))]]);
+  const pulls = [];
+  const calls = [];
+  const at = (ref) => commits.get(branches.get(ref) ?? ref) ?? null;
+  const json = (status, body) => new Response(body === undefined ? null : JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+  async function fetch(url, { method = "GET", headers = {}, body } = {}) {
+    const u = new URL(url);
+    calls.push(`${method} ${u.pathname}`);
+    if (token && !headers.authorization) return json(401, { message: "Requires authentication" });
+    const p = decodeURIComponent(u.pathname);
+    const rp = `/repos/${repo}`;
+    const b = body ? JSON.parse(body) : {};
+    let m;
+    if (method === "GET" && (m = p.match(new RegExp(`^${rp}/git/trees/(.+)$`)))) {
+      const s = at(m[1]);
+      if (!s) return json(404, { message: "Not Found" });
+      return json(200, { sha: branches.get(m[1]) ?? m[1], truncated: false, tree: [...s].map(([path, c]) => ({ path, type: "blob", sha: blobSha(c), size: Buffer.byteLength(c) })) });
+    }
+    if (method === "GET" && (m = p.match(new RegExp(`^${rp}/commits/(.+)$`)))) {
+      const sha = branches.get(m[1]) ?? (commits.has(m[1]) ? m[1] : null);
+      return sha ? json(200, { sha }) : json(404, { message: "Not Found" });
+    }
+    if (method === "GET" && (m = p.match(new RegExp(`^${rp}/git/ref/heads/(.+)$`)))) {
+      return branches.has(m[1]) ? json(200, { ref: `refs/heads/${m[1]}`, object: { sha: branches.get(m[1]), type: "commit" } }) : json(404, { message: "Not Found" });
+    }
+    if (method === "POST" && p === `${rp}/git/refs`) {
+      const name = b.ref.replace(/^refs\/heads\//, "");
+      if (branches.has(name)) return json(422, { message: "Reference already exists" });
+      if (!commits.has(b.sha)) return json(422, { message: "Object does not exist" });
+      branches.set(name, b.sha);
+      return json(201, { ref: b.ref, object: { sha: b.sha } });
+    }
+    if ((m = p.match(new RegExp(`^${rp}/contents/(.+)$`)))) {
+      const path = m[1];
+      if (method === "GET") {
+        const s = at(u.searchParams.get("ref") ?? branch);
+        if (!s || !s.has(path)) return json(404, { message: "Not Found" });
+        const c = s.get(path);
+        return json(200, { type: "file", path, sha: blobSha(c), encoding: "base64", content: Buffer.from(c).toString("base64") });
+      }
+      if (method === "PUT") {
+        const on = b.branch ?? branch;
+        const s = at(on);
+        if (!s) return json(404, { message: "Branch not found" });
+        if (s.has(path) && b.sha !== blobSha(s.get(path))) return json(b.sha ? 409 : 422, { message: b.sha ? `${path} does not match ${b.sha}` : "Invalid request.\n\n\"sha\" wasn't supplied." });
+        const next = new Map(s);
+        const c = Buffer.from(b.content, "base64").toString("utf8");
+        next.set(path, c);
+        const sha = commit(next);
+        branches.set(on, sha);
+        return json(s.has(path) ? 200 : 201, { content: { path, sha: blobSha(c) }, commit: { sha, message: b.message } });
+      }
+    }
+    if (method === "POST" && p === `${rp}/pulls`) {
+      if (!branches.has(b.head) || !branches.has(b.base)) return json(422, { message: "Validation Failed" });
+      const pr = { number: pulls.length + 1, html_url: `https://github.com/${repo}/pull/${pulls.length + 1}`, title: b.title, body: b.body, draft: !!b.draft, head: { ref: b.head }, base: { ref: b.base }, state: "open" };
+      pulls.push(pr);
+      return json(201, pr);
+    }
+    if (method === "GET" && p === "/search/code") {
+      const q = u.searchParams.get("q") ?? "";
+      const quals = Object.fromEntries([...q.matchAll(/(\w+):(\S+)/g)].map((x) => [x[1], x[2]]));
+      if (quals.repo !== repo) return json(422, { message: "Validation Failed" });
+      const terms = q.replace(/\w+:\S+/g, " ").trim();
+      const items = [...at(branch)].filter(([path, c]) => (!quals.path || path.startsWith(`${quals.path}/`) || path === quals.path) && matches(`${path}\n${c}`, terms))
+        .map(([path, c]) => ({ name: path.split("/").at(-1), path, sha: blobSha(c) }));
+      return json(200, { total_count: items.length, incomplete_results: false, items });
+    }
+    return json(404, { message: `the fake has no ${method} ${p}` });
+  }
+
+  return { fetch, branches, pulls, calls, files: (ref = branch) => Object.fromEntries(at(ref) ?? []) };
+}

package/platform/connectors/github.mjs

@@ -0,0 +1,105 @@
+// The GitHub connector (EE-037): one repository, at one branch, under one folder, through the REST
+// API with plain fetch (no SDK). Reads come from the branch; a write opens a draft pull request
+// against it, and merging the pull request is what accepts the write (Torian's choice, 2026-10-28).
+//
+//   repo     owner/name
+//   ref      the branch reads come from and pull requests target (default main)
+//   root     the folder inside the repository the source covers (default the whole repository)
+//   token    the name of the environment variable holding a token (default GITHUB_TOKEN); the
+//            token itself is never stored. Without one, only public repositories can be read.
+//   api      the API base (default https://api.github.com; GitHub Enterprise has its own)
+//   search   api (default): code search, which covers the default branch only, falling back to a
+//            scan when it is refused; scan: read every text file under root and match
+//   writes   pull-request (default) or none
+//   fetch    a fetch function (default globalThis.fetch); the evals pass a fake GitHub here
+//
+// version is the blob SHA GitHub reports, which is the git blob SHA-1 of the content. read also
+// gives the branch's commit and a permalink to the file at that commit, which is what to cite.
+
+import { blobSha, isText, matches, safePath } from "../../knowledge/connectors/contract.mjs";
+
+export function connect({ id = "github", repo, ref = "main", root = "", token = "GITHUB_TOKEN", api = "https://api.github.com", search = "api", writes = "pull-request", fetch: f = globalThis.fetch } = {}) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo ?? "")) throw new Error(`the github connector needs repo as owner/name, not ${repo}`);
+  if (writes === "direct") throw new Error("the github connector writes by pull request or not at all");
+  const base = root ? safePath(root) : "";
+  const full = (p) => (base ? `${base}/${safePath(p)}` : safePath(p));
+  const inside = (p) => !base || p.startsWith(`${base}/`);
+  const rel = (p) => (base ? p.slice(base.length + 1) : p);
+  const enc = (p) => p.split("/").map(encodeURIComponent).join("/");
+  const web = api === "https://api.github.com" ? "https://github.com" : api.replace(/\/api\/v3\/?$/, "");
+
+  async function gh(method, path, body) {
+    const secret = process.env[token];
+    const res = await f(`${api}${path}`, { method, headers: { accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28", "user-agent": "mentura",
+      ...(secret ? { authorization: `Bearer ${secret}` } : {}), ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+    if (res.status === 404 && method === "GET") return null;
+    const data = res.status === 204 ? null : await res.json().catch(() => null);
+    if (!res.ok) {
+      const why = res.status === 401 ? `no valid token in ${token}` : res.status === 403 ? `forbidden (token scope, or a rate limit)` : data?.message ?? res.statusText;
+      const e = new Error(`GitHub ${method} ${path}: ${res.status} ${why}`);
+      e.status = res.status;
+      throw e;
+    }
+    return data;
+  }
+
+  const head = async () => (await gh("GET", `/repos/${repo}/commits/${encodeURIComponent(ref)}`))?.sha ?? null;
+  const tree = async () => {
+    const t = await gh("GET", `/repos/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`);
+    if (!t) throw new Error(`${repo} has no branch ${ref}`);
+    if (t.truncated) throw new Error(`${repo}@${ref} is too large for one tree listing; set root to a smaller folder`);
+    return t.tree.filter((x) => x.type === "blob" && inside(x.path));
+  };
+  const contents = async (p, at = ref) => {
+    const x = await gh("GET", `/repos/${repo}/contents/${enc(full(p))}?ref=${encodeURIComponent(at)}`);
+    return x && !Array.isArray(x) && x.type === "file" ? x : null;
+  };
+  const decode = (x) => Buffer.from(x.content ?? "", x.encoding === "base64" ? "base64" : "utf8").toString("utf8");
+
+  return {
+    id, kind: "github", writes, repo, ref, root: base,
+    async list(prefix = "") {
+      const pre = prefix ? safePath(prefix) : "";
+      return (await tree()).map((x) => ({ path: rel(x.path), version: x.sha })).filter((x) => !pre || x.path === pre || x.path.startsWith(`${pre}/`)).sort((a, b) => a.path.localeCompare(b.path));
+    },
+    async read(p) {
+      const x = await contents(p);
+      if (!x) return null;
+      const commit = await head();
+      return { path: safePath(p), content: decode(x), version: x.sha, ...(commit ? { commit, permalink: `${web}/${repo}/blob/${commit}/${enc(full(p))}` } : {}) };
+    },
+    async version(p) {
+      return (await contents(p))?.sha ?? null;
+    },
+    async search(query, { limit = 50 } = {}) {
+      if (search === "api") {
+        try {
+          const q = `${query} repo:${repo}${base ? ` path:${base}` : ""}`;
+          const r = await gh("GET", `/search/code?q=${encodeURIComponent(q)}&per_page=${Math.min(limit, 100)}`);
+          return (r?.items ?? []).filter((x) => inside(x.path)).map((x) => ({ path: rel(x.path), version: x.sha })).slice(0, limit);
+        } catch (e) { if (![403, 422].includes(e.status)) throw e; }
+      }
+      const out = [];
+      for (const x of await tree()) {
+        if (out.length >= limit) break;
+        if (!isText(x.path)) continue;
+        const c = await contents(rel(x.path));
+        if (c && matches(`${rel(x.path)}\n${decode(c)}`, query)) out.push({ path: rel(x.path), version: x.sha });
+      }
+      return out;
+    },
+    async write(p, content, { message, title } = {}) {
+      if (writes === "none") throw new Error(`${id} is read-only`);
+      const path = full(p);
+      const from = (await gh("GET", `/repos/${repo}/git/ref/heads/${enc(ref)}`))?.object?.sha;
+      if (!from) throw new Error(`${repo} has no branch ${ref}`);
+      const branch = `mentura/${path.replace(/[^\w.-]+/g, "-").slice(0, 60)}-${Date.now().toString(36)}`;
+      await gh("POST", `/repos/${repo}/git/refs`, { ref: `refs/heads/${branch}`, sha: from });
+      const existing = await contents(p, branch);
+      const put = await gh("PUT", `/repos/${repo}/contents/${enc(path)}`, { message: message ?? `Update ${path}`, content: Buffer.from(content, "utf8").toString("base64"), branch, ...(existing ? { sha: existing.sha } : {}) });
+      const pr = await gh("POST", `/repos/${repo}/pulls`, { title: title ?? message ?? `Update ${path}`, head: branch, base: ref, draft: true,
+        body: `${message ?? `Update ${path}`}\n\nOpened by Mentura. Merging this pull request accepts the write.` });
+      return { path: safePath(p), version: put?.content?.sha ?? blobSha(content), commit: put?.commit?.sha, pull_request: { number: pr.number, url: pr.html_url, branch } };
+    },
+  };
+}

package/platform/integrations/jev.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Jev (TypeSafe), for typed judgments (platform, EE-041): reads one Naive request on stdin (state,
+// model, questions), sends it in chunks, and prints {model, answers, usage} on stdout. The framework
+// builds the request and reads the answers (purpose/frameworks/idea-map, product-anatomy); only
+// this side names the vendor and the credential.
+//
+//   node purpose/frameworks/idea-map/ideamap.mjs request <venture> | TYPESAFE_API_KEY=... node platform/integrations/jev.mjs
+
+const ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+const key = process.env.TYPESAFE_API_KEY ?? process.env.TYPESAFEAI_API_KEY;
+if (!key) { console.error("TYPESAFE_API_KEY is not set: tag with the founder's agent instead"); process.exit(3); }
+let input = "";
+for await (const c of process.stdin) input += c;
+const req = JSON.parse(input);
+const keys = Object.keys(req.questions);
+const size = Number(process.env.JEV_CHUNK ?? 260);
+const chunks = Array.from({ length: Math.ceil(keys.length / size) }, (_, i) => keys.slice(i * size, (i + 1) * size));
+const out = { model: null, answers: {}, usage: { input_tokens: 0, output_tokens: 0 }, requests: chunks.length };
+const t0 = Date.now();
+await Promise.all(chunks.map(async (ks) => {
+  const res = await fetch(ENDPOINT, { method: "POST", headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ ...req, questions: Object.fromEntries(ks.map((k) => [k, req.questions[k]])) }), signal: AbortSignal.timeout(120000) });
+  if (!res.ok) throw new Error(`TypeSafe returned ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  const r = await res.json();
+  out.model = r.model;
+  Object.assign(out.answers, r.answers);
+  out.usage.input_tokens += r.usage?.input_tokens ?? 0; out.usage.output_tokens += r.usage?.output_tokens ?? 0;
+}));
+out.ms = Date.now() - t0;
+console.log(JSON.stringify(out));

package/platform/integrations/langsmith-docket.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// The docket's evidence as a LangSmith experiment (platform, EE-041, EE-075): the scenario states
+// become a dataset (each with its expected next step and source), and one scored run of the docket
+// and the judge becomes an experiment over it, with docket_right, docket_function_right, judge_right
+// and agree as feedback on each row. Each run of this script adds one experiment, so versions of the
+// docket can be compared side by side.
+//
+//   node schema/docket-eval.mjs --answers a.json --json | LANGSMITH_API_KEY=... node platform/integrations/langsmith-docket.mjs [--name <experiment>]
+
+import { randomUUID } from "node:crypto";
+import { states } from "../../schema/docket-eval.mjs";
+
+const API = (process.env.LANGSMITH_ENDPOINT ?? "https://api.smith.langchain.com") + "/api/v1";
+const key = process.env.LANGSMITH_API_KEY;
+if (!key) { console.error("LANGSMITH_API_KEY is not set"); process.exit(3); }
+const headers = { "x-api-key": key, "content-type": "application/json" };
+const call = async (method, path, body) => {
+  const r = await fetch(API + path, { method, headers, ...(body ? { body: JSON.stringify(body) } : {}) });
+  if (!r.ok) throw new Error(`${method} ${path}: LangSmith answered ${r.status}: ${(await r.text()).slice(0, 300)}`);
+  return r.status === 204 ? null : r.json();
+};
+let input = "";
+for await (const c of process.stdin) input += c;
+const scored = JSON.parse(input);
+const arg = (k, d) => (process.argv.includes(k) ? process.argv[process.argv.indexOf(k) + 1] : d);
+
+const NAME = "Naive: docket scenarios";
+const list = states();
+let [dataset] = await call("GET", `/datasets?name=${encodeURIComponent(NAME)}`);
+if (!dataset) dataset = await call("POST", "/datasets", { name: NAME, description: "Venture states where the right next step is argued from a cited source (schema/examples/docket-scenarios.json). Labels are an agent's draft until the founder reviews them." });
+const have = await call("GET", `/examples?dataset=${dataset.id}&limit=100`);
+const byState = new Map(have.map((e) => [e.inputs.state, e]));
+for (const st of list) if (!byState.has(st.id)) {
+  const e = await call("POST", "/examples", { dataset_id: dataset.id, inputs: { state: st.id, phase: st.phase, situation: st.scenario.situation, decisions: st.decisions.map((d) => ({ id: d.id, question: d.question, function: d.function.id, render: d.render, held_by: d.held_by ?? null })) },
+    outputs: { decision: st.expected.decision, function: st.expected.function, why: st.scenario.why, source: st.scenario.source } });
+  byState.set(st.id, e);
+}
+
+const name = arg("--name", `docket ${new Date().toISOString().slice(0, 16)}`);
+const session = await call("POST", "/sessions", { name, reference_dataset_id: dataset.id, description: `docket next ${scored.docket_next}, function ${scored.docket_function}${scored.judge_next != null ? `; judge next ${scored.judge_next}, agree ${scored.docket_judge_agree}` : ""}` });
+const now = new Date().toISOString();
+const post = [];
+const feedback = [];
+for (const r of scored.rows) {
+  const id = randomUUID();
+  const dotted = `${now.replace(/[-:]/g, "").replace(".", "").replace("Z", "")}000Z${id}`;
+  post.push({ id, trace_id: id, dotted_order: dotted, name: "docket", run_type: "chain", start_time: now, end_time: now, session_id: session.id, reference_example_id: byState.get(r.state).id,
+    inputs: byState.get(r.state).inputs, outputs: { docket: r.docket, judge: r.judge ?? null }, extra: { metadata: { framework: "naive", state: r.state } } });
+  for (const k of ["docket_right", "docket_function_right", "judge_right", "agree"]) if (r[k] != null) feedback.push({ run_id: id, key: k, score: r[k] ? 1 : 0 });
+}
+await call("POST", "/runs/batch", { post });
+for (const f of feedback) await call("POST", "/feedback", f);
+console.log(JSON.stringify({ dataset: dataset.id, experiment: session.id, name, rows: post.length, url: `https://smith.langchain.com/o/${session.tenant_id}/datasets/${dataset.id}/compare?selectedSessions=${session.id}` }));