naive-framework 0.1.0 → 0.3.0

package/interface/brand.mjs

@@ -0,0 +1,215 @@
+// The brand and asset verbs of the CLI (mentura brand ..., mentura assets ...). Every write goes
+// through the router, so it is checked against its schema and logged in provenance; the logic lives
+// in schema/brand.mjs and schema/assets.mjs.
+//
+//   mentura assets add <public/file> --venture <id> --source <who or url> --license <id> --credit <who>
+//                                     [--alt <text>] [--decorative] [--as person]
+//                                     register a file in public/; code fills its facts (J-2, J-4)
+//   mentura assets fill --venture <id>          refill every entry's facts from its file, by code (J-4)
+//   mentura assets alt <public/file> --text <alt> --venture <id> [--as person]
+//                                     write alt text; an agent's waits for a person to confirm it
+//   mentura assets confirm <public/file> --venture <id> --by <name> [--confirm <public/file>]
+//                                     a person confirms the alt text as it stands (J-4)
+//   mentura assets remote <url> --venture <id> --license <id> --credit <who> [--id <raw id>] [--alt <text>] [--note <text>]
+//                                     record a remote image as a link with a note in raw/ (J-3)
+//   mentura assets hosts <host,host> --venture <id>   set the hosts an agent may fetch from (J-3)
+//   mentura assets check|facts --venture <id>
+//   mentura brand tokens|css|head|check|voice --venture <id> [--json]
+//   mentura brand resolve <route> --venture <id>      the brand at a route, nearer context winning (Y-5, T-2)
+//   mentura brand terms <package> --venture <id>      the terms a package sees (Y-2)
+//   mentura brand sitemap --venture <id> --base <url> [--out <file>]   sitemap.xml from the marketing sitemap (P-26)
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { call, ventureDir } from "./router.mjs";
+import { agentFromEnv, record as prov } from "./provenance.mjs";
+import { altStatement, checkAssets, facts as allFacts, factsOf, REGISTER, registerOf } from "../schema/assets.mjs";
+import { brandOf, checkBrand, resolveBrand, sitemapOf, sitemapXml, termsFor, tokens, voice } from "../schema/brand.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
+
+const VERSION = "0.1.0";
+const today = () => new Date().toISOString();
+
+/** The facts code reads, in the register's shape. */
+export const factsFor = (dir, path) => {
+  const f = factsOf(readFileSync(ventureFile(dir, path)));
+  return Object.fromEntries(Object.entries({ type: f.type, width: f.width, height: f.height, sizes: f.sizes, bytes: f.bytes, sha256: f.sha256, filled_at: today() }).filter(([, v]) => v !== undefined));
+};
+
+const emptyRegister = () => ({ version: VERSION, assets: [] });
+
+/** Writes the register through the router: schema first, then provenance. */
+export async function writeRegister(venture, workspace, reg, { actor = "agent", note } = {}) {
+  return call({ venture, route: "public/assets", action: "write", input: reg, actor, workspace, via: "cli", provenance: { note } });
+}
+
+/** Registers one file in public/ with its source, license and credit; code fills its facts. */
+export async function addAsset({ venture, workspace, path, source, license, credit, alt, decorative, origin_url, design_system, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  if (!path?.startsWith("public/")) return { ok: false, error: `${path} is not in public/` };
+  if (!existsSync(ventureFile(dir, path))) return { ok: false, error: `${path} is not in ${venture}` };
+  const reg = registerOf(dir) ?? emptyRegister();
+  const entry = Object.fromEntries(Object.entries({ path, source, license, credit, alt: alt ? { text: alt, by: actor === "person" ? "person" : "agent" } : undefined, decorative: decorative || undefined, origin_url, design_system, facts: factsFor(dir, path) }).filter(([, v]) => v !== undefined));
+  reg.assets = [...reg.assets.filter((a) => a.path !== path), entry].sort((a, b) => a.path.localeCompare(b.path));
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `registered ${path}; facts read by code` });
+  if (w.ok && alt && actor === "person") prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, alt), agent: agentFromEnv("person", "cli"), note: `alt text of ${path} written by a person` });
+  return w.ok ? { ok: true, result: { registered: path, facts: entry.facts, alt: entry.alt ?? null } } : w;
+}
+
+/** Refills every entry's facts from its file. Only code writes facts. */
+export async function fill({ venture, workspace }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir);
+  if (!reg) return { ok: false, error: `${venture} has no ${REGISTER}; register a file first: mentura assets add public/<file> ...` };
+  const changed = [], missing = [];
+  for (const a of reg.assets) {
+    if (!existsSync(ventureFile(dir, a.path))) { missing.push(a.path); continue; }
+    const f = factsFor(dir, a.path);
+    if (!a.facts || ["type", "width", "height", "bytes", "sha256"].some((k) => (a.facts[k] ?? null) !== (f[k] ?? null))) { a.facts = f; changed.push(a.path); }
+  }
+  const listed = new Set(reg.assets.map((a) => a.path));
+  const unregistered = allFacts(dir).map((x) => x.path).filter((p) => !listed.has(p));
+  if (changed.length) { const w = await writeRegister(venture, workspace, reg, { note: `facts filled by code: ${changed.join(", ")}` }); if (!w.ok) return w; }
+  return { ok: true, result: { filled: changed, missing, unregistered } };
+}
+
+/** Writes alt text. An agent's carries agent provenance until a person confirms it; a person's is confirmed as written. */
+export async function setAlt({ venture, workspace, path, text, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir);
+  const a = reg?.assets.find((x) => x.path === path);
+  if (!a) return { ok: false, error: `${path} is not registered; mentura assets add ${path} first` };
+  a.alt = { text, by: actor === "person" ? "person" : "agent" };
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `alt text of ${path} by ${a.alt.by}` });
+  if (!w.ok) return w;
+  if (actor === "person") prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, text), agent: agentFromEnv("person", "cli"), note: `alt text of ${path} written by a person` });
+  return { ok: true, result: { path, alt: a.alt, confirmed: actor === "person" } };
+}
+
+/** A person confirms an alt text exactly as it stands. The confirmation is bound to the text: change it and it is pending again. */
+export function confirmAlt({ venture, workspace, path, by }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  if (!by) return { ok: false, error: "say who is confirming: --by <name>" };
+  const a = registerOf(dir)?.assets.find((x) => x.path === path);
+  if (!a?.alt?.text) return { ok: false, error: `${path} has no alt text to confirm` };
+  const e = prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, a.alt.text), agent: agentFromEnv("person", "cli", { id: by }), note: `${by} confirmed the alt text of ${path}: ${a.alt.text}` });
+  return { ok: true, result: { path, alt: a.alt.text, confirmed_by: by, provenance: e.hash } };
+}
+
+const rawId = (url) => {
+  const u = new URL(url);
+  const slug = `${u.host}-${u.pathname.split("/").filter(Boolean).pop() ?? "image"}`.toLowerCase().replace(/\.[a-z0-9]+$/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug.slice(0, 60) || "remote-image";
+};
+
+/**
+ * A remote image as a link with a note in raw/ (J-3): raw/sources/<id>/source.json says where it is,
+ * text.md is the note, and the register lists it under remote. Nothing is fetched here. The platform
+ * fetcher passes `fetched` (facts of the private original) and `copy` when it kept a public copy.
+ */
+export async function addRemote({ venture, workspace, url, license, credit, id, alt, note, fetched, copy, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  try { new URL(url); } catch { return { ok: false, error: `${url} is not a URL` }; }
+  const rid = id ?? rawId(url);
+  const reg = registerOf(dir) ?? emptyRegister();
+  if (!existsSync(join(ventureFile(dir, "raw/sources"), rid, "source.json"))) {
+    const w = await call({ venture, route: `raw/sources/${rid}`, action: "write", input: { id: rid, origin: url, title: `Remote image at ${new URL(url).host}`, fetched: today().slice(0, 10) }, actor, workspace, via: "cli", provenance: { note: "a remote image, kept as a link (J-3)" } });
+    if (!w.ok) return w;
+    const text = [`# Remote image`, "", `- Link: ${url}`, `- Host: ${new URL(url).host}`, `- License: ${license}`, `- Credit: ${credit ?? "(missing)"}`, ...(fetched ? [`- Fetched: ${fetched.type}${fetched.width ? `, ${fetched.width}x${fetched.height}` : ""}, ${fetched.bytes} bytes, sha256 ${fetched.sha256}`] : []), "",
+      copy ? `A copy is kept at ${copy}: the license allows it.` : "The venture links to this image. A full copy stays private (raw/sources/<id>/original.*, out of git) unless the license allows one.", ...(note ? ["", note] : []), ""].join("\n");
+    writeFileSync(join(ventureFile(dir, "raw/sources"), rid, "text.md"), text);
+    prov(dir, { entity: `raw/sources/${rid}/text.md`, route: `raw/sources/${rid}`, activity: "write", agent: agentFromEnv(actor === "person" ? "person" : "agent", "cli"), note: "the note beside a remote image (J-3)" });
+  }
+  const entry = Object.fromEntries(Object.entries({ id: rid, url, license, credit, alt: alt ? { text: alt, by: actor === "person" ? "person" : "agent" } : undefined, fetched, copy }).filter(([, v]) => v !== undefined));
+  reg.remote = [...(reg.remote ?? []).filter((r) => r.url !== url), entry];
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `remote image ${url}` });
+  return w.ok ? { ok: true, result: { remote: url, raw: `raw/sources/${rid}/`, copy: copy ?? null } } : w;
+}
+
+/** The hosts an agent may fetch from, a setting the platform fetcher enforces (J-3). */
+export async function setHosts({ venture, workspace, hosts, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir) ?? emptyRegister();
+  reg.remote_hosts = hosts;
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `hosts an agent may fetch from: ${hosts.join(", ") || "none"}` });
+  return w.ok ? { ok: true, result: { remote_hosts: hosts } } : w;
+}
+
+/** mentura brand ... and mentura assets ...: returns the exit code. */
+export async function main(argv, { workspace } = {}) {
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const flag = (n) => argv.includes(`--${n}`);
+  const pos = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && !["json", "decorative"].includes(argv[i - 1].slice(2))));
+  const [group, verb, arg] = pos;
+  const venture = opt("venture");
+  const actor = opt("as") === "person" ? "person" : "agent";
+  const show = (r, text) => {
+    if (!r.ok) { console.error(r.error ?? JSON.stringify(r, null, 2)); return 1; }
+    console.log(flag("json") || text === undefined ? JSON.stringify(r.result, null, 2) : text);
+    return 0;
+  };
+  if (!venture) { console.error(`mentura ${group} ${verb ?? ""}: --venture <id> is required`); return 2; }
+  const dir = ventureDir(venture, workspace);
+  if (!dir) { console.error(`no venture ${venture}`); return 1; }
+
+  if (group === "assets") {
+    if (verb === "add") return show(await addAsset({ venture, workspace, path: arg, source: opt("source"), license: opt("license"), credit: opt("credit"), alt: opt("alt"), decorative: flag("decorative"), origin_url: opt("origin-url"), design_system: opt("design-system"), actor }), `registered: ${arg}`);
+    if (verb === "fill") { const r = await fill({ venture, workspace }); return show(r, r.ok ? `filled: ${r.result.filled.length ? r.result.filled.join(", ") : "nothing changed"}${r.result.unregistered.length ? `\nnot registered: ${r.result.unregistered.join(", ")}` : ""}` : undefined); }
+    if (verb === "alt") return show(await setAlt({ venture, workspace, path: arg, text: opt("text"), actor }), `alt text of ${arg} written by ${actor}${actor === "agent" ? "; a person confirms it with mentura assets confirm" : ""}`);
+    if (verb === "confirm") {
+      // The person types the path to confirm, as with foundation statements (EE-051).
+      if (opt("confirm") !== arg) { console.error(`not confirmed: pass --confirm ${arg} to confirm the alt text of ${arg} as it stands`); return 1; }
+      return show(confirmAlt({ venture, workspace, path: arg, by: opt("by") ?? process.env.MENTURA_PERSON }), `confirmed: alt text of ${arg}`);
+    }
+    if (verb === "remote") return show(await addRemote({ venture, workspace, url: arg, license: opt("license"), credit: opt("credit"), id: opt("id"), alt: opt("alt"), note: opt("note"), actor }), `linked: ${arg}`);
+    if (verb === "hosts") return show(await setHosts({ venture, workspace, hosts: (arg ?? "").split(",").map((h) => h.trim()).filter(Boolean), actor }), `remote_hosts: ${arg ?? "none"}`);
+    if (verb === "facts") return show({ ok: true, result: allFacts(dir) }, allFacts(dir).map((x) => `${x.path}  ${x.type}${x.width ? ` ${x.width}x${x.height}` : ""}  ${x.bytes} bytes`).join("\n") || "public/ is empty");
+    if (verb === "check") {
+      const r = checkAssets(dir);
+      if (flag("json")) console.log(JSON.stringify(r, null, 2));
+      else { for (const e of r.errors) console.log(`error    ${e}`); for (const p of r.pending) console.log(`pending  ${p.path}: alt text by ${p.by}, not confirmed by a person`); console.log(r.ok ? `assets: ${r.assets} files, ${r.remote} remote links, ${r.pending.length} alt texts pending` : `assets: ${r.errors.length} errors`); }
+      return r.ok ? 0 : 1;
+    }
+  }
+
+  if (group === "brand") {
+    const brand = brandOf(dir);
+    const need = () => { console.error(`${venture} has no brand yet: write marketing/brand.json (mentura marketing/brand template)`); return 1; };
+    if (verb === "tokens" || verb === "css" || verb === "head") {
+      if (!brand) return need();
+      const t = tokens(dir, brand);
+      return show({ ok: true, result: verb === "tokens" ? t.tokens : verb === "head" ? t.head : t.css }, verb === "css" ? t.css.trimEnd() : undefined);
+    }
+    if (verb === "resolve") { if (!brand) return need(); return show({ ok: true, result: resolveBrand(brand, arg ?? "") }); }
+    if (verb === "terms") { const t = termsFor(dir, arg); return show({ ok: true, result: t }, t.terms.map((x) => `${x.term}  (${x.from}): ${x.meaning}`).join("\n") || `no terms reach ${arg}`); }
+    if (verb === "voice") {
+      const v = opt("text") !== undefined ? { violations: (await import("../schema/brand.mjs")).voiceCheck(opt("text"), brand ? resolveBrand(brand, opt("for") ?? "").voice.rules : []) } : voice(dir, brand);
+      const lines = v.violations.map((x) => `${x.file ? `${x.file}:` : "line "}${x.line}  "${x.found}" breaks ${x.rule}${x.use ? `; use "${x.use}"` : ""}`);
+      if (flag("json")) console.log(JSON.stringify(v, null, 2)); else console.log(lines.join("\n") || "keeps to the voice rules");
+      return v.violations.length ? 1 : 0;
+    }
+    if (verb === "check") {
+      const r = checkBrand(dir);
+      if (flag("json")) console.log(JSON.stringify(r, null, 2));
+      else { for (const e of r.errors) console.log(`error  ${e}`); for (const w of r.warnings) console.log(`warn   ${w}`); console.log(r.ok ? "brand: ok" : `brand: ${r.errors.length} errors`); }
+      return r.ok ? 0 : 1;
+    }
+    if (verb === "sitemap") {
+      const s = sitemapOf(dir);
+      if (!s) { console.error(`${venture} has no marketing sitemap yet: mentura operations/marketing/sitemap run, then write it to marketing/sitemap`); return 1; }
+      let xml;
+      try { xml = sitemapXml(s.record, opt("base") ?? ""); } catch (e) { console.error(`${e.message}; pass --base https://<your site>`); return 1; }
+      if (opt("out")) { const f = resolvePath(opt("out")); mkdirSync(dirname(f), { recursive: true }); writeFileSync(f, xml); console.log(`wrote ${opt("out")}: ${s.record.pages.length} pages from ${s.file}`); return 0; }
+      process.stdout.write(xml);
+      return 0;
+    }
+  }
+  console.error(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//   mentura")).map((l) => l.slice(5)).join("\n"));
+  return 2;
+}

package/interface/cli/freshness.mjs

@@ -0,0 +1,59 @@
+// The freshness commands of the mentura CLI (Revalidating, V-1 to V-8). mentura.mjs hands these
+// commands here; the logic is schema/freshness.mjs.
+//
+//   mentura revalidate <target> --venture <id> [--reason <text>] [--as person] [--json]
+//          target: tag:<route or file> (the record and what depends on it), path:<folder>,
+//          package:<name>, or a plain route or file (a tag); a plain folder is refused with the tags to use
+//   mentura revalidate --pivot --venture <id> [--reason <text>]    every assumption in the validation package
+//   mentura verify <route|folder> --venture <id> [--reason <text>] [--as person]
+//          checked and still right, unchanged: its age starts again
+//   mentura phase <phase> --venture <id> --as person [--reason <text>]
+//          the venture changes phase; records with a per-phase profile go stale
+//   mentura freshness --venture <id> [--json] [--now <iso>] [--freeze <out dir>]
+//          what is fresh, stale, expired or a live hole; --freeze writes the static shell
+
+import { resolve } from "node:path";
+import { agentFromEnv } from "../provenance.mjs";
+import { ventureDir } from "../router.mjs";
+import { freeze, freshness, phase, revalidate, verify } from "../../schema/freshness.mjs";
+
+export const COMMANDS = ["revalidate", "verify", "phase", "freshness"];
+
+/** Runs one freshness command. Returns the exit code. */
+export async function main(cmd, argv, workspace) {
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const flag = (n) => argv.includes(`--${n}`);
+  const target = argv[1] && !argv[1].startsWith("--") ? argv[1] : undefined;
+  const venture = opt("venture");
+  const dir = venture && ventureDir(venture, workspace);
+  const print = (x) => console.log(typeof x === "string" ? x : JSON.stringify(x, null, 2));
+  if (!dir) { console.error(venture ? `no venture ${venture}` : `usage: mentura ${cmd} ${cmd === "freshness" ? "" : "<target> "}--venture <id>`); return venture ? 1 : 2; }
+  const by = agentFromEnv(opt("as") === "person" ? "person" : "agent", "cli");
+  const now = opt("now");
+  let r;
+  if (cmd === "revalidate") {
+    if (!target && !flag("pivot")) { console.error("usage: mentura revalidate <tag:route|path:folder|package:name|route> --venture <id>, or --pivot"); return 2; }
+    r = await revalidate(dir, flag("pivot") ? "pivot" : target, { reason: opt("reason"), by, now });
+  } else if (cmd === "verify") {
+    if (!target) { console.error("usage: mentura verify <route|folder> --venture <id>"); return 2; }
+    r = verify(dir, target, { reason: opt("reason"), by, now });
+  } else if (cmd === "phase") {
+    if (!target) { console.error("usage: mentura phase <phase> --venture <id> --as person"); return 2; }
+    // A phase change is the founder's decision: an agent may suggest it, not make it.
+    if (opt("as") !== "person") { console.error(`a phase change is a person's: run mentura phase ${target} --venture ${venture} --as person`); return 1; }
+    r = phase(dir, target, { reason: opt("reason"), by, now });
+  } else if (cmd === "freshness") {
+    if (opt("freeze")) r = await freeze(dir, resolve(opt("freeze")), { now });
+    else { const f = await freshness(dir, { now }); print(flag("json") ? f : [`${f.venture} (${f.phase}): ${f.summary.fresh} fresh, ${f.summary.stale} stale, ${f.summary.expired} expired, ${f.summary.holes} live ${f.summary.holes === 1 ? "hole" : "holes"}, of ${f.summary.records} records.`,
+      ...f.items.filter((i) => i.state !== "fresh").map((i) => `  ${i.state.padEnd(7)} ${i.route}: ${i.reasons.map((x) => x.note).join("; ")}`),
+      ...f.copies.filter((c) => c.state !== "fresh").map((c) => `  ${c.state.padEnd(7)} ${c.path} (copy of ${c.parent}): ${c.note}`),
+      ...f.warnings.map((w) => `warning: ${w}`)].join("\n")); return 0; }
+  }
+  if (!r.ok) {
+    console.error(r.error);
+    if (r.suggest) console.error(`  ${r.suggest.join("\n  ")}\n  or, for the whole folder: mentura revalidate ${r.or} --venture ${venture}`);
+    return 1;
+  }
+  print(flag("json") ? r.result : r.result.note ?? r.result);
+  return 0;
+}

package/interface/cli/guard.mjs

@@ -0,0 +1,6 @@
+// The framework's global error for the command line (E-8, interface/boundaries.mjs). Imported first, so a
+// broken data model or manifest answers with recovery steps before any module that reads it loads.
+import { frameworkHealth, globalError } from "../boundaries.mjs";
+
+const fw = frameworkHealth();
+if (fw) { console.error(globalError(fw).error); process.exit(1); }

package/interface/cli/mentura.mjs

@@ -12,9 +12,12 @@
 //   mentura migrate --from <project> --venture <id|dir> [--apply]
 //                                                   alias of naive migrate: an agent rewrites a project as Naive records (EE-076)
 //   mentura typegen                                 alias of naive typegen (EE-073)
+//   mentura steps <payload|run|check|waterfall|provenance|confirm> --venture <id> [--answers <file>] [--speculate] [--stream]
+//                                                   model steps (use model, EE-073): schema/model-steps.mjs
 //   mentura accept <route> --venture <id> [--confirm <route>]
 //                                                   a person accepts an agent's draft of a gated record;
-//                                                   one holding a foundation statement asks you to type the route
+//                                                   one holding a foundation statement asks you to type the route;
+//                                                   [--pick <letter>] [--by <name>] accepts one of drafts kept side by side
 //   mentura decide <decision> --venture <id> --by <name> [--answer <text>] [--confirm <decision>]
 //                                                   a person makes a decision: approves its wording or gives their own (EE-058)
 //   mentura propose --venture <id> --input <file.json> [--as <role>]
@@ -29,16 +32,30 @@
 //          a collection item is <route>/<id> (purpose/product/kettle); a nested venture is its
 //          folder path (--venture studio/print); system/overview view shows the venture at a glance
 //          [--derived-from a,b] [--decision <id>] [--note <text>]   provenance for a write (EE-031)
+//          [--confidence <n>]   a score computed before the write, read by the gate's confidence rules
 //          knowledge/catalog run builds the catalog over the venture's sources; knowledge/search run
 //          --value <query> finds items in any of them (EE-037)
 //          purpose/validation/assess run lists what is missing and asks to fill it in or run as is;
 //          --as-is runs it anyway (EE-050)
+//          [--where status=active|trial,phase=build] filters a read; --hierarchy shows how it resolved
+//          a package's own route (validation, packages/product) reads its state; (go-to-market) is a
+//          route group; venture read is the manifest, venture check runs every boundary
 //   mentura baseline --venture <id>                 adopt existing records into the provenance log
+//   mentura revalidate <tag:route|path:folder|package:name|route> --venture <id> [--pivot] [--reason <text>]
+//                                                   mark records stale on demand; a plain folder is refused for exact tags (Revalidating)
+//   mentura verify <route|folder> --venture <id>    checked and still right, unchanged: its age starts again
+//   mentura phase <phase> --venture <id> --as person   change phase; per-phase records go stale
+//   mentura freshness --venture <id> [--freeze <out dir>]   what is fresh, stale, expired or a live hole
+//   mentura <route> navigate|head --venture <id> [--session <s>] [--task <text>] [--prefetch a,b | --no-prefetch] [--stream]
+//                                                   read a route header first, with layout once per session, template and prefetch
+//   mentura batch --venture <id> --input <calls.json> [--stream]
+//                                                   run a list of {route, action, input} calls, reporting each as it finishes
 //
 // The workspace is MENTURA_WORKSPACE, else --workspace <dir>, else this repository's instance/.
 // Writes default to an agent actor; --as person is for a person at the keyboard, and a gated
 // record written by an agent lands in <venture>/_drafts/ for a person to accept.
 
+import "./guard.mjs"; // wf/writes hook: a broken framework file answers with recovery steps (E-8)
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -46,7 +63,10 @@ import { call, draftOf, files, glob, groups, repo, routes, routesMd, ventureDir,
 import { agentFromEnv, entries, record } from "../provenance.mjs";
 import { FRAME, filesOf } from "../../schema/foundation.mjs";
 import { approve, decisions, propose } from "../../schema/decisions.mjs";
+// Gate group hook (X-2): held drafts kept side by side.
+import { pick as pickDraft, settle as settleDraft } from "../../schema/gate-drafts.mjs";
 import { asRouted, findVenture } from "./find-venture.mjs";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 // The danger zone (EE-051): a foundation statement is accepted or confirmed only when the person types
 // its name, at the prompt or with --confirm <name>.
@@ -68,7 +88,7 @@ const here = !argv.includes("--venture") && !argv.includes("--workspace") ? find
 if (here) { argv.push("--venture", asRouted(here).venture, "--workspace", asRouted(here).workspace); process.env.MENTURA_WORKSPACE = asRouted(here).workspace; }
 const opt = (name) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : undefined; };
 const flag = (name) => argv.includes(`--${name}`);
-const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && !["json"].includes(argv[i - 1].slice(2))));
+const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && !["json", "hierarchy"].includes(argv[i - 1].slice(2))));
 const workspace = opt("workspace") ? resolve(opt("workspace")) : undefined;
 const out = (x) => console.log(typeof x === "string" ? x : JSON.stringify(x, null, 2));
 
@@ -95,6 +115,9 @@ if (cmd === "ventures") {
   process.exit(0);
 }
 
+// Brand hook: mentura brand ... and mentura assets ... (Y-2..Y-4, J-2..J-4, T-1, T-2, P-24, P-26) live in interface/brand.mjs.
+if (cmd === "brand" || cmd === "assets") process.exit(await (await import("../brand.mjs")).main(argv, { workspace }));
+
 if (cmd === "add") {
   // Imports one function into a venture (EE-047, EE-048, EE-071). department is the alias for function for one release.
   const v = opt("venture");
@@ -108,6 +131,27 @@ if (cmd === "typegen") {
   process.exit(p.status ?? 1);
 }
 
+// Upgrades hook (M-12, E-7, V-9, Z-4): these commands live in their own modules; this only dispatches.
+//   mentura triggers --venture <id> [--fire] [--json]
+//                                                   the venture's triggers, their runs and open failures; --fire runs what new events start
+//   mentura stale --venture <id> [--json]           summaries whose system of record changed since they were written
+//   mentura notify --venture <id> --source <id> --path <p> [--version <v>]
+//                                                   a system of record says <p> changed: mark what reads it stale (a webhook does this on Mentura)
+//   mentura adapt <adapter> --venture <id>          write a harness's entry files into the venture (claude-code, codex, cursor)
+//   mentura adapters [verify [<adapter>]] [--json]  the adapters, or run the framework's tests an adapter must pass
+if (["triggers", "stale", "notify", "adapt", "adapters"].includes(cmd)) {
+  const d = ["triggers", "stale", "notify", "adapt"].includes(cmd) ? (opt("venture") ? ventureDir(opt("venture"), workspace) : null) : null;
+  if (cmd !== "adapters" && !d) { console.error(opt("venture") ? `no venture ${opt("venture")}` : `mentura ${cmd} needs --venture <id>`); process.exit(2); }
+  const pass = (...names) => names.flatMap((n) => argv.flatMap((a, i) => (a === `--${n}` ? [a, ...(argv[i + 1] && !argv[i + 1].startsWith("--") ? [argv[i + 1]] : [])] : [])));
+  const args = cmd === "triggers" ? ["schema/triggers.mjs", d, ...pass("fire", "json")]
+    : cmd === "stale" ? ["schema/stale.mjs", d, ...pass("json")]
+    : cmd === "notify" ? ["schema/stale.mjs", d, "--notify", ...pass("source", "path", "version", "json")]
+    : cmd === "adapt" ? ["interface/adapters.mjs", "adapt", action ?? "", d, ...pass("json")]
+    : ["interface/adapters.mjs", ...positional.slice(1), ...pass("json")];
+  const p = spawnSync("node", [join(repo, args[0]), ...args.slice(1)], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
 if (cmd === "migrate" && (opt("from") || flag("apply"))) {
   // migrate means rewriting an outside project into a new venture (EE-076): the same as naive migrate.
   const v = opt("venture");
@@ -127,6 +171,16 @@ if (cmd === "upgrade" || cmd === "migrate") {
   process.exit(p.status ?? 1);
 }
 
+// Model steps hook (use model, EE-073): mentura steps <payload|run|check|waterfall|provenance|confirm> --venture <id> [...].
+// The logic is schema/model-steps.mjs; this passes the venture folder and the other arguments through.
+if (cmd === "steps") {
+  const v = opt("venture"), d = v && ventureDir(v, workspace);
+  if (!d || !action) usage();
+  const pass = argv.slice(argv.indexOf("steps") + 1).filter((a, i, all) => !["--venture", "--workspace"].includes(a) && !["--venture", "--workspace"].includes(all[i - 1]));
+  const p = spawnSync("node", [join(repo, "schema/model-steps.mjs"), d, ...pass], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
 if (cmd === "init") {
   // The venture scaffold lives in schema/init-venture.mjs; this passes the options through.
   const id = opt("id");
@@ -148,22 +202,27 @@ if (cmd === "accept") {
   if (!d) { console.error(`${rt} is not a record route, or no venture ${venture}`); process.exit(1); }
   const draft = join(d.dir, d.draft);
   if (!existsSync(draft)) { console.error(`no draft of ${d.route} in ${venture}`); process.exit(1); }
+  // Gate group hook (X-2): drafts kept side by side are accepted one at a time with --pick <letter>.
+  let chosen;
+  try { chosen = pickDraft(d.dir, d.draft, opt("pick")); } catch (e) { console.error(e.message); process.exit(1); }
+  const chosenFile = join(d.dir, chosen);
   const recType = routes().find((x) => x.route === d.route || x.route === d.route.replace(/[^/]+$/, "[id]"))?.record;
   const touched = foundationOf(recType);
   if (touched.length) {
     const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
     const now = existsSync(join(d.dir, d.file)) ? JSON.parse(readFileSync(join(d.dir, d.file), "utf8")) : {};
-    const next = JSON.parse(readFileSync(draft, "utf8"));
+    const next = JSON.parse(readFileSync(chosenFile, "utf8"));
     const diff = touched.map((s) => `  ${s.id}:\n    now:   ${JSON.stringify(get(now, s.attribute) ?? null)}\n    draft: ${JSON.stringify(get(next, s.attribute) ?? null)}`).join("\n");
     const names = new Set([d.route, rt]);
     const confirmed = opt("confirm") !== undefined ? names.has(opt("confirm")) : await typed(d.route, `Accepting ${d.route} changes these foundation statements:\n${diff}`);
     if (!confirmed) { console.error("not accepted: the confirmation did not match"); process.exit(1); }
   }
-  const w = await call({ venture, route: d.route, action: "write", input: JSON.parse(readFileSync(draft, "utf8")), actor: "person", workspace, via: "cli",
-    provenance: { activity: "accept", derived_from: [d.draft], note: opt("note") } });
+  const w = await call({ venture, route: d.route, action: "write", input: JSON.parse(readFileSync(chosenFile, "utf8")), actor: "person", workspace, via: "cli",
+    provenance: { activity: "accept", derived_from: [chosen], note: opt("note") } });
   if (!w.ok) { console.error(w.error); process.exit(1); }
-  rmSync(draft);
-  out(`accepted: ${w.result.written}`);
+  // Gate group hook (X-2): removes the draft, its variants and sidecar, and decides the variants decision.
+  const settled = settleDraft(d.dir, d.draft, { picked: opt("pick") ?? "a", by: opt("by") });
+  out(`accepted: ${w.result.written}${settled.decision ? ` (draft ${settled.picked}; decision ${settled.decision} ${settled.decided ? "decided" : `not decided: ${settled.error}`})` : ""}`);
   process.exit(0);
 }
 
@@ -197,7 +256,7 @@ if (cmd === "understand") {
   // Mentura got wrong, and confirms the understanding before the ideas are routed.
   const venture = opt("venture"), dir = venture && ventureDir(venture, workspace);
   if (!dir) usage();
-  const hits = ["purpose/ideas/map.mdx", "purpose/ideas/graph.json"].filter((f) => existsSync(join(dir, f)));
+  const hits = ["purpose/ideas/map.mdx", "purpose/ideas/graph.json"].filter((f) => existsSync(ventureFile(dir, f)));
   if (!hits.length) { console.error(`${venture} has no idea map yet: map the idea dump first (purpose/ideas)`); process.exit(1); }
   if (!(await typed("ideas", `Confirming Mentura's understanding of your ideas: ${hits.join(", ")}`, "Your ideas are routed to their records from this understanding."))) { console.error("not confirmed: the confirmation did not match"); process.exit(1); }
   for (const f of hits) record(dir, { entity: f, route: f.endsWith(".mdx") ? "purpose/ideas" : "purpose/ideas/graph", activity: "confirm", statement: "ideas", agent: agentFromEnv("person", "cli"), note: opt("note") });
@@ -213,10 +272,10 @@ if (cmd === "confirm") {
   const s = FRAME.questions.flatMap((q) => q.statements).find((x) => x.id === id);
   if (!s?.record) { console.error(`${id} is not a foundation statement with a record (see mentura purpose/foundation run)`); process.exit(1); }
   const rt = routes().find((x) => x.record === s.record && x.collection !== "list")?.route ?? s.record;
-  const hits = filesOf(dir, s.record).filter((f) => existsSync(join(dir, f)));
+  const hits = filesOf(dir, s.record).filter((f) => existsSync(ventureFile(dir, f)));
   if (!hits.length) { console.error(`${venture} has no ${s.record} record to confirm`); process.exit(1); }
   const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
-  const shown = hits.map((f) => `  ${f}: ${JSON.stringify(get(JSON.parse(readFileSync(join(dir, f), "utf8")), s.attribute) ?? null)}`).join("\n");
+  const shown = hits.map((f) => `  ${f}: ${JSON.stringify(get(JSON.parse(readFileSync(ventureFile(dir, f), "utf8")), s.attribute) ?? null)}`).join("\n");
   if (!(await typed(id, `Confirming ${id} as yours:\n${shown}`))) { console.error("not confirmed: the confirmation did not match"); process.exit(1); }
   for (const f of hits) record(dir, { entity: f, route: rt, activity: "confirm", statement: id, agent: agentFromEnv("person", "cli"), note: opt("note") });
   out(`confirmed: ${id}`);
@@ -243,6 +302,13 @@ if (cmd === "baseline") {
   process.exit(0);
 }
 
+// Freshness (Revalidating, V-1 to V-8): revalidate, verify, phase and freshness live in ./freshness.mjs.
+if (["revalidate", "verify", "phase", "freshness"].includes(cmd)) process.exit(await (await import("./freshness.mjs")).main(cmd, argv, workspace));
+
+// Context hook (interface/context.mjs): navigate and head read a route header first, with its layout once per
+// session (--session), its template and prefetched refs (--task, --prefetch, --no-prefetch, --stream); batch runs
+// a list of calls with progress.
+if (["navigate", "head"].includes(action) || cmd === "batch") { const { cli } = await import("../context.mjs"); process.exit(await cli(argv, { workspace })); }
 if (!action) usage();
 const venture = opt("venture");
 if (!venture && !["template", "layout"].includes(action)) usage();
@@ -251,7 +317,12 @@ const src = opt("input");
 if (src) input = JSON.parse(src === "-" ? readFileSync(0, "utf8") : readFileSync(src, "utf8"));
 if (opt("value")) input = { ...(input ?? {}), value: Number.isNaN(Number(opt("value"))) ? opt("value") : Number(opt("value")) };
 if (flag("as-is")) input = { ...(input ?? {}), as_is: true };
+// wf/writes hook: --where k=v[,k=v] filters a read (L-10); --hierarchy returns its resolution levels (P-28).
+if (["read", "view"].includes(action) && opt("where")) input = { ...(input ?? {}), where: Object.fromEntries(opt("where").split(",").map((kv) => kv.split("=")).map(([k, ...v]) => [k, v.join("=").includes("|") ? v.join("=").split("|") : v.join("=")])) };
+if (["read", "view"].includes(action) && flag("hierarchy")) input = { ...(input ?? {}), hierarchy: true };
 const provenance = { derived_from: opt("derived-from")?.split(",").filter(Boolean), decision: opt("decision"), note: opt("note") };
+// Gate group hook (X-4): a confidence score computed before the write, for the gate's confidence rules.
+if (opt("confidence") !== undefined) provenance.confidence = Number(opt("confidence"));
 let r = await call({ venture, route: cmd, action, input, actor: opt("as") === "person" ? "person" : "agent", workspace, via: "cli", provenance });
 // Asks before running (EE-050): at a terminal, the person chooses; otherwise it prints both choices.
 if (r.ok && r.needs_input && !flag("json")) {
@@ -267,5 +338,5 @@ if (r.ok && r.needs_input && !flag("json")) {
 }
 if (!r.ok) { console.error(r.error ?? JSON.stringify(r.result, null, 2)); process.exit(1); }
 if (r.deprecated) console.error(`note: ${r.deprecated}`);
-const extra = ["not_found", "pending_draft", "fix", "needs_input"].some((k) => r[k]);
+const extra = ["not_found", "pending_draft", "fix", "needs_input", "errors", "filtered_out", "hierarchy", "stale"].some((k) => r[k]); // stale: V-9 (schema/stale.mjs)
 out(flag("json") || extra ? r : r.result);