naive-framework 0.0.0-stage → 0.2.0

package/packages/operations/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "operations",
+  "title": "Operations",
+  "kind": "core",
+  "purpose": "The departments, who hands what to whom, and whether the venture runs without the founder in every loop.",
+  "department": "service-delivery",
+  "departments": [
+    "service-delivery",
+    "customer-service",
+    "supply-chain",
+    "it",
+    "assets"
+  ],
+  "required": [
+    "department",
+    "handoff",
+    "validation-operations-readiness"
+  ],
+  "optional": [
+    "knowledge-sources",
+    "where-used"
+  ],
+  "refs": [
+    "team-plan",
+    "decision-rights"
+  ],
+  "planned": [],
+  "base": {
+    "discovery": 0.05,
+    "validation": 0.3,
+    "beachhead": 0.7,
+    "scale": 0.9,
+    "platform": 0.95
+  },
+  "when": [
+    {
+      "if": "people>=3",
+      "at_least": 0.7
+    },
+    {
+      "if": "offering:service",
+      "phase": "validation",
+      "at_least": 0.55
+    }
+  ],
+  "why": "Once more than a couple of people, or a service delivered by people, has to run",
+  "unlocks": [
+    "support agents",
+    "delivery workflows"
+  ],
+  "not_modeled": "Matters after Validation or under another governance model; kept for later, not computed (EE-069).",
+  "gates": [
+    "a person has confirmed every required record and every record this package reads"
+  ],
+  "schemas": [
+    "schema/department.schema.json",
+    "schema/handoff.schema.json",
+    "schema/validation-operations-readiness.schema.json",
+    "schema/knowledge-sources.schema.json",
+    "schema/where-used.schema.json"
+  ],
+  "templates": [],
+  "checks": [
+    "schema/check-validation.mjs",
+    "schema/check-sources.mjs",
+    "schema/check-where-used.mjs",
+    "schema/check-departments.mjs",
+    "schema/check-execution.mjs",
+    "schema/check-ready.mjs",
+    "schema/check-publication.mjs"
+  ],
+  "skill": null,
+  "use_model": []
+}

package/packages/partner/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "partner",
+  "title": "Partner",
+  "kind": "handoff",
+  "purpose": "the partners a product is offered to",
+  "for": "the partners a product is offered to",
+  "from": [
+    "foundation",
+    "product",
+    "marketing"
+  ],
+  "base": {
+    "discovery": 0.05,
+    "validation": 0.1,
+    "beachhead": 0.2,
+    "scale": 0.3,
+    "platform": 0.5
+  },
+  "when": [
+    {
+      "if": "partner_led",
+      "at_least": 0.9
+    }
+  ],
+  "why": "Only when the product is offered to partners who serve customers of their own",
+  "unlocks": [
+    "partner kit",
+    "co-marketing"
+  ],
+  "gates": [
+    "every core package it draws on is complete"
+  ],
+  "schemas": [],
+  "templates": [],
+  "checks": [],
+  "skill": null,
+  "use_model": []
+}

package/packages/people/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "people",
+  "title": "People",
+  "kind": "core",
+  "purpose": "Who the venture needs, what each person brings, and on what terms people join.",
+  "department": "human-capital",
+  "required": [
+    "validation-team",
+    "team-plan"
+  ],
+  "optional": [
+    "founder-agreement"
+  ],
+  "refs": [],
+  "planned": [],
+  "base": {
+    "discovery": 0.2,
+    "validation": 0.4,
+    "beachhead": 0.6,
+    "scale": 0.8,
+    "platform": 0.8
+  },
+  "when": [
+    {
+      "if": "team:looking",
+      "at_least": 0.9
+    },
+    {
+      "if": "team:cofounders",
+      "at_least": 0.8
+    },
+    {
+      "if": "hiring",
+      "at_least": 0.85
+    },
+    {
+      "if": "path:cofounder-first",
+      "at_least": 0.9
+    }
+  ],
+  "why": "When looking for a cofounder, with cofounders, or hiring",
+  "unlocks": [
+    "recruiting outreach",
+    "onboarding"
+  ],
+  "gates": [
+    "a person has confirmed every required record and every record this package reads"
+  ],
+  "schemas": [
+    "schema/validation-team.schema.json",
+    "schema/team-plan.schema.json",
+    "schema/founder-agreement.schema.json"
+  ],
+  "templates": [
+    "operations/templates/recruiting-brief.md"
+  ],
+  "checks": [
+    "schema/check-validation.mjs",
+    "schema/check-governance.mjs",
+    "schema/check-team.mjs"
+  ],
+  "skill": null,
+  "use_model": []
+}

package/packages/product/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "product",
+  "title": "Product",
+  "kind": "core",
+  "purpose": "What the venture offers, each product's role (flagship, substrate, wedge) and what it is offered to whom.",
+  "department": "products",
+  "required": [
+    "product"
+  ],
+  "optional": [
+    "anatomy-answers"
+  ],
+  "refs": [
+    "icp"
+  ],
+  "planned": [
+    "specs",
+    "roadmap"
+  ],
+  "base": {
+    "discovery": 0.6,
+    "validation": 0.9,
+    "beachhead": 1,
+    "scale": 1,
+    "platform": 1
+  },
+  "when": [
+    {
+      "if": "products>=1",
+      "at_least": 0.8
+    }
+  ],
+  "why": "Once a product idea exists",
+  "unlocks": [
+    "the engineering handoff: build what is specified"
+  ],
+  "gates": [
+    "a person has confirmed every required record and every record this package reads"
+  ],
+  "schemas": [
+    "schema/product.schema.json"
+  ],
+  "templates": [],
+  "checks": [
+    "schema/check-ventures.mjs"
+  ],
+  "skill": null,
+  "use_model": []
+}

package/packages/raw/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "raw",
+  "title": "Raw",
+  "kind": "raw",
+  "purpose": "Immutable captures and founder-supplied sources. dump/ holds captures. sources/[id]/ holds source.json and text.md. original.* stays out of git (EE-070).",
+  "required": [],
+  "optional": [],
+  "refs": [],
+  "gates": [
+    "immutable: append a capture, never edit one"
+  ],
+  "layer": "purpose",
+  "records": ["raw-source", "raw-text"],
+  "schemas": ["schema/raw-source.schema.json"],
+  "templates": [],
+  "checks": ["schema/check-data-packages.mjs"],
+  "skill": null,
+  "use_model": []
+}

package/packages/relationships/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "relationships",
+  "title": "Relationships",
+  "kind": "core",
+  "purpose": "The named accounts, partners and investors the venture works with.",
+  "department": "external-relationships",
+  "required": [
+    "account"
+  ],
+  "optional": [],
+  "refs": [
+    "icp"
+  ],
+  "planned": [
+    "partner records",
+    "investor records"
+  ],
+  "base": {
+    "discovery": 0,
+    "validation": 0.1,
+    "beachhead": 0.3,
+    "scale": 0.6,
+    "platform": 0.8
+  },
+  "when": [
+    {
+      "if": "partner_led",
+      "at_least": 0.8
+    },
+    {
+      "if": "offering:service",
+      "at_least": 0.6
+    }
+  ],
+  "why": "From Scale, or sooner when partner-led or a service",
+  "unlocks": [
+    "partner and investor updates"
+  ],
+  "not_modeled": "Matters after Validation or under another governance model; kept for later, not computed (EE-069).",
+  "gates": [
+    "a person has confirmed every required record and every record this package reads"
+  ],
+  "schemas": [
+    "schema/account.schema.json"
+  ],
+  "templates": [],
+  "checks": [
+    "schema/check-ventures.mjs"
+  ],
+  "skill": null,
+  "use_model": []
+}

package/packages/validation/package.json

@@ -0,0 +1,112 @@
+{
+  "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"
+  ],
+  "gate_rules": [
+    { "id": "validation-low-confidence", "routes": ["validation/**", "foundation/problem", "people/team"], "actors": ["agent"], "when": { "confidence_below": "confidence" }, "then": "owner", "note": "A validation record an agent is not confident in goes to its function owner" }
+  ],
+  "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": [],
+  "use_cache": [
+    {
+      "route": "purpose/validation/assess",
+      "level": "record",
+      "life": "hours",
+      "vary": [
+        "day"
+      ]
+    }
+  ],
+  "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,51 @@
+---
+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 |
+| `adapter.json` | Mentura as Naive's first adapter, as Vercel is for Next.js: `mentura adapters verify mentura` runs the connector contract suite, the webhooks and the kits (Z-4) |
+| `kits/agent-upgrade/` | The agent-run upgrade behind `naive upgrade --agent`: an agent does the guides' by-hand steps on a staged copy, and the framework's checks decide (U-3). `stand-in-agent.mjs` runs offline |
+| `kits/validation-kickoff/` | An automation over the validation package: once the foundation is complete, it proposes the decision to start validating (M-12) |
+| `kits/test.mjs` | Tests for the kits, with the stand-in agent |
+| `webhooks/server.mjs` | Signed webhooks from systems of record: a change marks the summaries that read it stale (V-9). Secrets come from `NAIVE_WEBHOOK_SECRET_<SOURCE>` |
+| `webhooks/test.mjs` | Tests for the webhooks, offline |
+
+## 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/adapter.json

@@ -0,0 +1,15 @@
+{
+  "name": "mentura",
+  "title": "Mentura",
+  "kind": "platform",
+  "reads": ["knowledge/sources.json", "naive.config.json"],
+  "files": [],
+  "skills": null,
+  "verify": [
+    "platform/connectors/eval.mjs",
+    "platform/webhooks/test.mjs",
+    "platform/kits/test.mjs"
+  ],
+  "sources": [],
+  "note": "Mentura is Naive's first adapter, as Vercel is for Next.js (Z-4): it runs the framework's record contract over vendor sources (GitHub), receives systems of record's change notifications (webhooks) and holds the kits. It is verified when it passes the framework's tests: the connector contract suite (knowledge/connectors/suite.mjs) and the router over a GitHub source, both run by platform/connectors/eval.mjs, and the platform's tests of the framework hooks it implements."
+}

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();