@neuroverseos/governance 0.7.0 → 0.8.0

package/README.md

@@ -3,12 +3,51 @@
 [![npm version](https://img.shields.io/npm/v/@neuroverseos/governance)](https://www.npmjs.com/package/@neuroverseos/governance)
 [![license](https://img.shields.io/npm/l/@neuroverseos/governance)](LICENSE.md)
 
-**Control what AI can do — and how it behaves — across every app.**
+**Behavioral governance for AI systems.** Give meaning to behavior — meaning relative to the behavioral models that have been declared and governed.
 
-NeuroVerse is the governance layer for AI-powered devices. It gives users, developers, and organizations a single system to define permissions, behavioral personality, and role-based access — for smart glasses, phones, agents, or any AI-enabled product.
+Human intelligence and artificial intelligence are two different kinds of intelligence working together. All organizations, all systems, gather people around declared shared intent. NeuroverseOS tools help define those intentions into behaviors — and those behaviors become a constitution carried out at runtime.
 
-**Built for multi-agent systems:** when many agents are active, they all evaluate against the same deterministic governance model.  
-**Built for handoff:** governance is portable as world/plan artifacts, so teams can update policy quickly and hand it across agents, apps, and operators without rewriting core logic.
+NeuroverseOS is the universe where human and AI meet to work together, defined by the behaviors the organization has agreed upon. **Radiant** is the behavioral intelligence layer built on top: it reads what happened, compares it against what was declared, and tells you where the work aligns and where it drifts.
+
+Together they put you in a cocoon of behavior — not a cage, a cocoon. Something that holds your shape while you're becoming what you said you'd become.
+
+## Two products, one package
+
+| Layer | What it does | Who uses it |
+|---|---|---|
+| **NeuroverseOS** | Governance engine — worldmodel compiler, guard engine, lens system, plan enforcement | Developers building governed AI apps |
+| **Radiant** | Behavioral intelligence — reads activity, gives it meaning through the worldmodel, measures human-AI alignment | Teams and organizations (starting with Auki/ExoCortex) |
+
+Both ship in `@neuroverseos/governance`. Install once, use either or both.
+
+## Radiant — behavioral intelligence for collaboration
+
+Radiant gives meaning to behavior. It reads activity (GitHub commits, PRs, reviews), classifies each event by who did it (human, AI, or both together), extracts behavioral signals, identifies patterns through AI interpretation governed by the worldmodel, and produces a structured read:
+
+```bash
+npx @neuroverseos/governance radiant emergent aukiverse/posemesh \
+  --lens auki-builder --worlds ./worlds/
+```
+
+Output:
+
+```
+EMERGENT    — what patterns are visible in the team's work
+MEANING     — what it means against the worldmodel
+MOVE        — what to do about it (or "nothing's broken, keep shipping")
+ALIGNMENT   — L/C/N/R scores (human, AI, collaboration, composite)
+GOVERNANCE  — audit trail: which events triggered governance, on which side
+DEPTH       — what Radiant can see now vs what unlocks with more reads
+```
+
+Three scores nobody else measures:
+- **L** — is the human's work aligned with the declared model?
+- **C** — is the AI's output aligned with the declared model?
+- **N** — when human and AI work together, is shared meaning preserved through the worldmodel? This score only exists because the worldmodel exists.
+
+For the full Radiant documentation, see [`src/radiant/examples/auki/README.md`](src/radiant/examples/auki/README.md).
+
+## Governance engine — deterministic rules for AI
 
 ```
 What AI can do      →  Rules (permissions)

package/dist/{chunk-T6EQ7ZBG.js → chunk-MC6O5GV5.js}

@@ -145,17 +145,30 @@ function resolveLens(id) {
 }
 
 // src/radiant/core/scopes.ts
-function parseRepoScope(scope) {
+function parseScope(scope) {
   const cleaned = scope.replace(/^https?:\/\//, "").replace(/^github\.com\//, "").replace(/\.git$/, "").replace(/\/$/, "");
-  const parts = cleaned.split("/");
-  if (parts.length < 2 || !parts[0] || !parts[1]) {
+  const parts = cleaned.split("/").filter(Boolean);
+  if (parts.length === 0 || !parts[0]) {
     throw new Error(
-      `Cannot parse repo scope: "${scope}". Expected "owner/repo" or a GitHub URL.`
+      `Cannot parse scope: "${scope}". Expected "owner/repo" or "owner".`
     );
   }
-  return { owner: parts[0], repo: parts[1] };
+  if (parts.length === 1) {
+    return { type: "org", owner: parts[0] };
+  }
+  return { type: "repo", owner: parts[0], repo: parts[1] };
+}
+function parseRepoScope(scope) {
+  const parsed = parseScope(scope);
+  if (parsed.type === "org") {
+    throw new Error(
+      `Expected "owner/repo" but got org-level scope "${parsed.owner}". Use parseScope() for org-level.`
+    );
+  }
+  return parsed;
 }
 function formatScope(scope) {
+  if (scope.type === "org") return `${scope.owner} (org)`;
   return `${scope.owner}/${scope.repo}`;
 }
 
@@ -339,12 +352,46 @@ async function fetchJSON(url, headers) {
   }
   return await res.json();
 }
+async function fetchGitHubOrgActivity(scope, token, options = {}) {
+  const perPage = options.perPage ?? 100;
+  const headers = {
+    Authorization: `token ${token}`,
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "neuroverseos-radiant"
+  };
+  const repos = await fetchJSON(
+    `https://api.github.com/orgs/${scope.owner}/repos?sort=pushed&direction=desc&per_page=${perPage}`,
+    headers
+  );
+  const windowDays = options.windowDays ?? 14;
+  const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1e3);
+  const activeRepos = repos.filter(
+    (r) => new Date(r.pushed_at) >= since
+  );
+  const cappedRepos = activeRepos.slice(0, 10);
+  const allEvents = [];
+  const repoNames = [];
+  for (const repo of cappedRepos) {
+    const [owner, repoName] = repo.full_name.split("/");
+    try {
+      const repoScope = { type: "repo", owner, repo: repoName };
+      const events = await fetchGitHubActivity(repoScope, token, options);
+      allEvents.push(...events);
+      if (events.length > 0) repoNames.push(repo.full_name);
+    } catch {
+    }
+  }
+  allEvents.sort(
+    (a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)
+  );
+  return { events: allEvents, repos: repoNames };
+}
 function createMockGitHubAdapter(fixedEvents) {
   return async () => fixedEvents;
 }
 
 // src/radiant/adapters/exocortex.ts
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { join, resolve } from "path";
 function readExocortex(dirPath) {
   const dir = resolve(dirPath);
@@ -415,6 +462,46 @@ ${ctx.methods}`);
   }
   return sections.join("\n\n");
 }
+function readTeamExocortices(teamDir) {
+  const dir = resolve(teamDir);
+  if (!existsSync(dir)) return [];
+  const entries = readdirSync(dir);
+  const results = [];
+  for (const entry of entries) {
+    const entryPath = join(dir, entry);
+    try {
+      const stat = statSync(entryPath);
+      if (stat.isDirectory()) {
+        const ctx = readExocortex(entryPath);
+        if (ctx.filesLoaded > 0) {
+          results.push({ name: entry, context: ctx });
+        }
+      }
+    } catch {
+    }
+  }
+  return results;
+}
+function formatTeamExocorticesForPrompt(team) {
+  if (team.length === 0) return "";
+  const sections = [
+    "## Team Intent (cross-exocortex read)",
+    "",
+    `Reading ${team.length} team members' exocortices. Compare each person's`,
+    "stated intent against the observed activity AND against each other.",
+    "Surface: duplicate focus, missing coverage, silent pivots,",
+    "and areas where no one is carrying the work.",
+    ""
+  ];
+  for (const { name, context } of team) {
+    sections.push(`### ${name}`);
+    if (context.attention) sections.push(`**Attention:** ${context.attention.split("\n")[0]}`);
+    if (context.goals) sections.push(`**Goals:** ${context.goals.split("\n").slice(0, 3).join("; ")}`);
+    if (context.sprint) sections.push(`**Sprint:** ${context.sprint.split("\n").slice(0, 3).join("; ")}`);
+    sections.push("");
+  }
+  return sections.join("\n");
+}
 function summarizeExocortex(ctx) {
   if (ctx.filesLoaded === 0) return "no exocortex files found";
   const loaded = [];
@@ -428,7 +515,7 @@ function summarizeExocortex(ctx) {
 }
 
 // src/radiant/memory/palace.ts
-import { readFileSync as readFileSync2, writeFileSync, mkdirSync, readdirSync, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
 import { join as join2, resolve as resolve2 } from "path";
 function writeRead(exocortexDir, frontmatter, text) {
   const dir = resolve2(exocortexDir, "radiant", "reads");
@@ -560,7 +647,7 @@ function loadUntriggeredCounts(filepath) {
 function loadPriorReads(exocortexDir) {
   const dir = resolve2(exocortexDir, "radiant", "reads");
   if (!existsSync2(dir)) return [];
-  const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+  const files = readdirSync2(dir).filter((f) => f.endsWith(".md")).sort();
   const reads = [];
   for (const filename of files) {
     const filepath = join2(dir, filename);
@@ -995,6 +1082,14 @@ ${jargonTable}
 
 For example: don't say "update the worldmodel." Say "add a line to your strategy file."
 
+## When the same invariant keeps firing
+
+If the prior read history or the current evidence shows the same worldmodel invariant being triggered repeatedly (by the same side \u2014 human or AI), name it in MEANING and ask the real question:
+
+  "This invariant has been tested N times across M reads. Always on the [human/AI] side. Either the team needs alignment on WHY this rule exists \u2014 or the team is telling you something the worldmodel hasn't absorbed yet."
+
+Don't just say "invariant held." Say what it means that people keep pushing against the same wall.
+
 ## Health is a valid read
 
 If the activity is healthy and aligned with the worldmodel, SAY SO. Don't fabricate problems. Over-prescription is a voice failure. Legitimate outputs include:
@@ -1379,9 +1474,21 @@ async function emergent(input) {
       priorReadContext = formatPriorReadsForPrompt(priorReads);
     }
   }
-  const events = await fetchGitHubActivity(input.scope, input.githubToken, {
-    windowDays
-  });
+  let events;
+  let orgRepos;
+  if (input.scope.type === "org") {
+    const orgResult = await fetchGitHubOrgActivity(
+      input.scope,
+      input.githubToken,
+      { windowDays }
+    );
+    events = orgResult.events;
+    orgRepos = orgResult.repos;
+  } else {
+    events = await fetchGitHubActivity(input.scope, input.githubToken, {
+      windowDays
+    });
+  }
   const classified = classifyEvents(events);
   const signals = extractSignals(classified);
   const scores = computeScores(signals, input.worldmodelContent !== "");
@@ -1537,12 +1644,16 @@ export {
   composeSystemPrompt,
   checkForbiddenPhrases,
   think,
+  parseScope,
   parseRepoScope,
   formatScope,
   fetchGitHubActivity,
+  fetchGitHubOrgActivity,
   createMockGitHubAdapter,
   readExocortex,
   formatExocortexForPrompt,
+  readTeamExocortices,
+  formatTeamExocorticesForPrompt,
   summarizeExocortex,
   writeRead,
   updateKnowledge,

package/dist/cli/neuroverse.cjs

@@ -2003,7 +2003,7 @@ __export(world_loader_exports, {
 async function loadWorldFromDirectory(dirPath) {
   const { readFile: readFile4 } = await import("fs/promises");
   const { join: join18 } = await import("path");
-  const { readdirSync: readdirSync9 } = await import("fs");
+  const { readdirSync: readdirSync10 } = await import("fs");
   async function readJson(filename) {
     const filePath = join18(dirPath, filename);
     try {
@@ -2036,7 +2036,7 @@ async function loadWorldFromDirectory(dirPath) {
   const rules = [];
   try {
     const rulesDir = join18(dirPath, "rules");
-    const ruleFiles = readdirSync9(rulesDir).filter((f) => f.endsWith(".json")).sort();
+    const ruleFiles = readdirSync10(rulesDir).filter((f) => f.endsWith(".json")).sort();
     for (const file of ruleFiles) {
       try {
         const content = await readFile4(join18(rulesDir, file), "utf-8");
@@ -2183,12 +2183,12 @@ async function addGuard(worldDir, input) {
 async function addRule(worldDir, input) {
   const { readFile: readFile4, writeFile: writeFile6, mkdir: mkdir3 } = await import("fs/promises");
   const { join: join18 } = await import("path");
-  const { readdirSync: readdirSync9 } = await import("fs");
+  const { readdirSync: readdirSync10 } = await import("fs");
   const rulesDir = join18(worldDir, "rules");
   await mkdir3(rulesDir, { recursive: true });
   let nextNum = 1;
   try {
-    const existing = readdirSync9(rulesDir).filter((f) => f.match(/^rule-\d+\.json$/)).sort();
+    const existing = readdirSync10(rulesDir).filter((f) => f.match(/^rule-\d+\.json$/)).sort();
     if (existing.length > 0) {
       const lastFile = existing[existing.length - 1];
       const match = lastFile.match(/rule-(\d+)\.json/);
@@ -2849,27 +2849,27 @@ ${candidates.map((c) => `  - ${c}`).join("\n")}`
 }
 async function collectMarkdownSources(inputPath) {
   const { stat, readFile: rf, readdir } = await import("fs/promises");
-  const { join: pathJoin, extname: extname4, basename: basename4 } = await import("path");
+  const { join: pathJoin, extname: extname4, basename: basename5 } = await import("path");
   const stats = await stat(inputPath);
   if (stats.isFile()) {
     const content = await rf(inputPath, "utf-8");
-    return [{ filename: basename4(inputPath), content }];
+    return [{ filename: basename5(inputPath), content }];
   }
   if (stats.isDirectory()) {
     const sources = [];
-    await collectDir(inputPath, sources, rf, pathJoin, extname4, basename4);
+    await collectDir(inputPath, sources, rf, pathJoin, extname4, basename5);
     sources.sort((a, b) => a.filename.localeCompare(b.filename));
     return sources;
   }
   throw new Error(`Input path is neither a file nor a directory: ${inputPath}`);
 }
-async function collectDir(dir, sources, rf, pathJoin, extname4, basename4) {
+async function collectDir(dir, sources, rf, pathJoin, extname4, basename5) {
   const { readdir } = await import("fs/promises");
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = pathJoin(dir, entry.name);
     if (entry.isDirectory()) {
-      await collectDir(fullPath, sources, rf, pathJoin, extname4, basename4);
+      await collectDir(fullPath, sources, rf, pathJoin, extname4, basename5);
     } else if (entry.isFile() && extname4(entry.name).toLowerCase() === ".md") {
       const content = await rf(fullPath, "utf-8");
       sources.push({ filename: entry.name, content });
@@ -3557,12 +3557,12 @@ function printInsight(finding2) {
 async function main2(argv = process.argv.slice(2)) {
   try {
     const args = parseArgs2(argv);
-    const { basename: basename4 } = await import("path");
+    const { basename: basename5 } = await import("path");
     write(`
 NeuroVerse World Builder
 `);
     write(`
-Analyzing: ${basename4(args.inputPath)}
+Analyzing: ${basename5(args.inputPath)}
 `);
     const derivedPath = args.outputDir ? `${args.outputDir}/source.nv-world.md` : ".neuroverse/build-output.nv-world.md";
     const { mkdir: mkdir3 } = await import("fs/promises");
@@ -20473,17 +20473,30 @@ var init_think = __esm({
 });
 
 // src/radiant/core/scopes.ts
-function parseRepoScope(scope) {
+function parseScope(scope) {
   const cleaned = scope.replace(/^https?:\/\//, "").replace(/^github\.com\//, "").replace(/\.git$/, "").replace(/\/$/, "");
-  const parts = cleaned.split("/");
-  if (parts.length < 2 || !parts[0] || !parts[1]) {
+  const parts = cleaned.split("/").filter(Boolean);
+  if (parts.length === 0 || !parts[0]) {
+    throw new Error(
+      `Cannot parse scope: "${scope}". Expected "owner/repo" or "owner".`
+    );
+  }
+  if (parts.length === 1) {
+    return { type: "org", owner: parts[0] };
+  }
+  return { type: "repo", owner: parts[0], repo: parts[1] };
+}
+function parseRepoScope(scope) {
+  const parsed = parseScope(scope);
+  if (parsed.type === "org") {
     throw new Error(
-      `Cannot parse repo scope: "${scope}". Expected "owner/repo" or a GitHub URL.`
+      `Expected "owner/repo" but got org-level scope "${parsed.owner}". Use parseScope() for org-level.`
     );
   }
-  return { owner: parts[0], repo: parts[1] };
+  return parsed;
 }
 function formatScope(scope) {
+  if (scope.type === "org") return `${scope.owner} (org)`;
   return `${scope.owner}/${scope.repo}`;
 }
 var init_scopes = __esm({
@@ -20658,6 +20671,40 @@ async function fetchJSON(url, headers) {
   }
   return await res.json();
 }
+async function fetchGitHubOrgActivity(scope, token, options = {}) {
+  const perPage = options.perPage ?? 100;
+  const headers = {
+    Authorization: `token ${token}`,
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "neuroverseos-radiant"
+  };
+  const repos = await fetchJSON(
+    `https://api.github.com/orgs/${scope.owner}/repos?sort=pushed&direction=desc&per_page=${perPage}`,
+    headers
+  );
+  const windowDays = options.windowDays ?? 14;
+  const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1e3);
+  const activeRepos = repos.filter(
+    (r) => new Date(r.pushed_at) >= since
+  );
+  const cappedRepos = activeRepos.slice(0, 10);
+  const allEvents = [];
+  const repoNames = [];
+  for (const repo of cappedRepos) {
+    const [owner, repoName] = repo.full_name.split("/");
+    try {
+      const repoScope = { type: "repo", owner, repo: repoName };
+      const events = await fetchGitHubActivity(repoScope, token, options);
+      allEvents.push(...events);
+      if (events.length > 0) repoNames.push(repo.full_name);
+    } catch {
+    }
+  }
+  allEvents.sort(
+    (a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)
+  );
+  return { events: allEvents, repos: repoNames };
+}
 var KNOWN_AI_LOGINS, KNOWN_AI_CO_AUTHOR_NAMES;
 var init_github2 = __esm({
   "src/radiant/adapters/github.ts"() {
@@ -21372,6 +21419,14 @@ ${jargonTable}
 
 For example: don't say "update the worldmodel." Say "add a line to your strategy file."
 
+## When the same invariant keeps firing
+
+If the prior read history or the current evidence shows the same worldmodel invariant being triggered repeatedly (by the same side \u2014 human or AI), name it in MEANING and ask the real question:
+
+  "This invariant has been tested N times across M reads. Always on the [human/AI] side. Either the team needs alignment on WHY this rule exists \u2014 or the team is telling you something the worldmodel hasn't absorbed yet."
+
+Don't just say "invariant held." Say what it means that people keep pushing against the same wall.
+
 ## Health is a valid read
 
 If the activity is healthy and aligned with the worldmodel, SAY SO. Don't fabricate problems. Over-prescription is a voice failure. Legitimate outputs include:
@@ -21768,9 +21823,21 @@ async function emergent(input) {
       priorReadContext = formatPriorReadsForPrompt(priorReads);
     }
   }
-  const events = await fetchGitHubActivity(input.scope, input.githubToken, {
-    windowDays
-  });
+  let events;
+  let orgRepos;
+  if (input.scope.type === "org") {
+    const orgResult = await fetchGitHubOrgActivity(
+      input.scope,
+      input.githubToken,
+      { windowDays }
+    );
+    events = orgResult.events;
+    orgRepos = orgResult.repos;
+  } else {
+    events = await fetchGitHubActivity(input.scope, input.githubToken, {
+      windowDays
+    });
+  }
   const classified = classifyEvents(events);
   const signals = extractSignals(classified);
   const scores = computeScores(signals, input.worldmodelContent !== "");
@@ -22220,6 +22287,8 @@ function parseArgs27(argv) {
     query: void 0,
     model: void 0,
     exocortex: void 0,
+    teamExocortex: void 0,
+    view: void 0,
     json: false,
     help: false,
     rest: []
@@ -22247,6 +22316,12 @@ function parseArgs27(argv) {
       case "--exocortex":
         result.exocortex = argv[++i];
         break;
+      case "--team-exocortex":
+        result.teamExocortex = argv[++i];
+        break;
+      case "--view":
+        result.view = argv[++i];
+        break;
       case "--json":
         result.json = true;
         break;
@@ -22388,7 +22463,7 @@ async function cmdEmergent(args) {
     );
     process.exit(1);
   }
-  const scope = parseRepoScope(scopeStr);
+  const scope = parseScope(scopeStr);
   const lensId = args.lens ?? process.env.RADIANT_LENS;
   if (!lensId) {
     process.stderr.write(
@@ -22426,6 +22501,15 @@ ${DIM3}Set it to a GitHub PAT with repo read access.${RESET3}
   const worldmodelContent = loadWorldmodelContent2(worldsPath);
   const model = args.model ?? process.env.RADIANT_MODEL;
   const ai = createAnthropicAI(anthropicKey, model || void 0);
+  const view = args.view ?? process.env.RADIANT_VIEW ?? "community";
+  const validViews = ["community", "team", "full"];
+  if (!validViews.includes(view)) {
+    process.stderr.write(
+      `${RED2}Error:${RESET3} --view must be community, team, or full. Got "${view}".
+`
+    );
+    process.exit(1);
+  }
   const exocortexPath = args.exocortex ?? process.env.RADIANT_EXOCORTEX;
   let exocortexStatus = "not loaded";
   if (exocortexPath) {
@@ -22433,7 +22517,8 @@ ${DIM3}Set it to a GitHub PAT with repo read access.${RESET3}
     exocortexStatus = summarizeExocortex(ctx);
   }
   process.stderr.write(
-    `${DIM3}Scope:      ${scope.owner}/${scope.repo}${RESET3}
+    `${DIM3}Scope:      ${scope.type === "org" ? scope.owner + " (entire org)" : scope.owner + "/" + scope.repo}${RESET3}
+${DIM3}View:       ${view}${RESET3}
 ${DIM3}Lens:       ${lensId}${RESET3}
 ${DIM3}Model:      ${model ?? "claude-sonnet-4-20250514 (default)"}${RESET3}
 ${DIM3}ExoCortex:  ${exocortexStatus}${RESET3}