@inkobytes/nexus 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.3 - 2026-06-03
+
+- Collapsed large `nexus doctor` Git Privacy floods into grouped per-root summaries with sample paths.
+- Prioritized `CONTINUITY.md` and `memories/` samples first so agent-local issues stay visible.
+- Collapsed shared agent roots like `.claude/`, `.codex/`, and `.gemini/` into one concise Git Privacy note for repos that intentionally track them.
+- Colorized `nexus doctor` output and grouped findings under clearer action buckets like `Fix the following` and `Review / informational`.
+- Added `.nexus/config.json` support for `doctor.allowTrackedAgentTrees` so intentionally tracked shared agent trees can be treated as informational.
+
 ## 1.0.1 - 2026-06-02
 
 - Added colorized `nexus help` output for a more readable CLI experience.

package/README.md

@@ -166,6 +166,8 @@ Doctor reports grouped issues:
 - missing Nexus files
 - package script exfiltration and install-hook risks
 - package privacy risks for local/private files
+- grouped Git Privacy summaries for tracked private/local trees, with shared agent dirs collapsed into one concise note
+- colorized action buckets so fixes and informational lock notes are easier to scan
 - stale nexus locks
 - missing agent instructions specifically for nexus
 - missing continuity and memory scaffolds
@@ -175,6 +177,18 @@ With `--fix`, Nexus creates safe missing scaffolds and updates managed protocol
 
 With `--json`, Nexus prints the same health sections as structured JSON for tools such as Inkobytes reports.
 
+If a private repo intentionally tracks shared agent trees like `.claude/`, `.codex/`, or `.gemini/`, you can mark that as allowed in `.nexus/config.json`:
+
+```json
+{
+  "doctor": {
+    "allowTrackedAgentTrees": true
+  }
+}
+```
+
+With that setting, `nexus doctor` keeps the shared-agent-tree note as informational instead of repeating an untrack fix.
+
 Use `doctor` for audit or repair. Do not make it the normal first command for every agent session.
 
 ### `nexus soul [--file <path>] [--status | --remove]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -93,6 +93,8 @@ This project uses Nexus for multi-agent coordination.
 ### Nexus Rules
 
 - Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
+- Nexus is agent-native and file-native, not feature-native: commit and release by file as soon as the file reaches a coherent checkpoint.
+- Do not hold claims while waiting to bundle related files into one feature commit; that blocks other agents who may need the file next.
 - Release finished work through Nexus: \`nexus release <path> "commit message"\`.
 - Use \`nexus next @Agent\` for the next safe queue task.
 - Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.
@@ -345,6 +347,7 @@ export default function doctor(args) {
   const fix = args.includes('--fix');
   const json = args.includes('--json');
   const root = cwd();
+  const colors = createColors();
   const sections = {
     'Nexus Files': [],
     'Agent Instructions': [],
@@ -363,8 +366,8 @@ export default function doctor(args) {
   const config = getConfig(root);
 
   if (!json) {
-    console.log(`Nexus doctor${fix ? ' --fix' : ''}`);
-    console.log(`Repo: ${root}\n`);
+    console.log(colors.bold(colors.cyan(`Nexus doctor${fix ? ' --fix' : ''}`)));
+    console.log(`${colors.dim('Repo:')} ${root}\n`);
   }
 
   const nexusProtocolFiles = ['_NEXUS_CONSTITUTION.md', '_NEXUS_QUEUE.md', '_NEXUS_STANDUP.md'];
@@ -410,7 +413,7 @@ export default function doctor(args) {
     sections['Package Privacy'].push(issue);
   }
 
-  for (const issue of scanGitPrivacy(root)) {
+  for (const issue of scanGitPrivacy(root, config)) {
     sections['Git Privacy'].push(issue);
   }
 
@@ -656,35 +659,95 @@ export default function doctor(args) {
   }
 
   if (changes.length) {
-    console.log('Applied fixes:');
-    for (const change of changes) console.log(`  - ${change}`);
+    console.log(colors.bold(colors.green('Applied fixes')));
+    for (const change of changes) console.log(`  ${colors.green('-')} ${change}`);
     console.log('');
   }
 
   let problemCount = 0;
   for (const [title, entries] of Object.entries(sections)) {
-    console.log(`[${title}]`);
+    console.log(colors.bold(colors.cyan(`[${title}]`)));
     if (!entries.length) {
-      console.log('  OK');
+      console.log(`  ${colors.green('OK')}`);
       console.log('');
       continue;
     }
 
-    for (const entry of entries) {
-      const prefix = entry.ok ? '-' : '!';
-      console.log(`  ${prefix} ${entry.issue}`);
-      if (entry.fix) console.log(`    Fix: ${entry.fix}`);
-      if (!entry.ok) problemCount++;
-    }
+    const actionable = entries.filter((entry) => !entry.ok);
+    const informational = entries.filter((entry) => entry.ok);
+    problemCount += actionable.length;
+
+    if (actionable.length) renderEntryBucket('Fix the following', actionable, colors.yellow, colors.red, title, colors);
+    if (informational.length) renderEntryBucket('Review / informational', informational, colors.blue, colors.green, title, colors);
     console.log('');
   }
 
   if (problemCount) {
-    console.log('Some issues need attention. Safe scaffold fixes: `nexus doctor --fix`.');
+    console.log(colors.bold(colors.yellow('Some issues need attention.')));
+    console.log(colors.dim('Safe scaffold fixes: `nexus doctor --fix`.'));
     return;
   }
 
-  console.log('All checked Nexus categories are ready.');
+  console.log(colors.bold(colors.green('All checked Nexus categories are ready.')));
+}
+
+function renderEntryBucket(label, entries, headingColor, markerColor, sectionTitle, colors) {
+  console.log(`  ${headingColor(label)}`);
+  const groups = groupEntriesForDisplay(entries, sectionTitle);
+  for (const group of groups) {
+    if (group.label) {
+      console.log(`    ${colors.bold(group.label)}`);
+    }
+    for (const entry of group.entries) {
+      const baseIndent = group.label ? '      ' : '    ';
+      const detailIndent = group.label ? '        ' : '      ';
+      const prefix = entry.ok ? '-' : '!';
+      console.log(`${baseIndent}${markerColor(prefix)} ${entry.issue}`);
+      if (entry.details) {
+        for (const detail of entry.details) {
+          console.log(`${detailIndent}${colors.dim(detail)}`);
+        }
+      }
+      if (entry.fix) {
+        console.log(`${detailIndent}${colors.bold('Fix:')} ${colors.dim(entry.fix)}`);
+      }
+    }
+  }
+}
+
+function groupEntriesForDisplay(entries, sectionTitle) {
+  const groups = [];
+  const grouped = new Map();
+
+  for (const entry of entries) {
+    const label = entry.displayGroup || inferDisplayGroup(entry.issue, sectionTitle);
+    if (!label) {
+      groups.push({ label: '', entries: [entry] });
+      continue;
+    }
+    if (!grouped.has(label)) {
+      const group = { label, entries: [] };
+      grouped.set(label, group);
+      groups.push(group);
+    }
+    grouped.get(label).entries.push(entry);
+  }
+
+  return groups;
+}
+
+function inferDisplayGroup(issue, sectionTitle) {
+  if (sectionTitle === 'Locks') {
+    const lockMatch = issue.match(/^(?:Stale lock on|Active lock on|Unverified claim on) ([^ ]+)/);
+    if (lockMatch) return lockMatch[1];
+  }
+
+  if (sectionTitle === 'Queue Authorship') {
+    const taskMatch = issue.match(/^Task "([^"]+)"/);
+    if (taskMatch) return taskMatch[1];
+  }
+
+  return '';
 }
 
 function extractReadyQueueSection(content) {
@@ -843,6 +906,27 @@ const PRIVATE_GIT_PATHS = [
   'USER.md',
 ];
 
+const GIT_PRIVACY_COLLAPSE_ROOTS = [
+  '.agent-session-logs',
+  '.agent-*',
+  '.agy',
+  '.antigravitycli',
+  '.claude',
+  '.codex',
+  '.gemini',
+  '.nexus/local',
+  'docs-priv',
+  'scratch',
+  'session-logs',
+];
+
+const GIT_PRIVACY_AGENT_ROOTS = new Set([
+  '.agy',
+  '.claude',
+  '.codex',
+  '.gemini',
+]);
+
 function scanPackagePrivacy(root) {
   const packagePath = join(root, 'package.json');
   if (!existsSync(packagePath)) return [];
@@ -874,7 +958,7 @@ function scanPackagePrivacy(root) {
   return issues;
 }
 
-function scanGitPrivacy(root) {
+function scanGitPrivacy(root, config) {
   const gitDir = join(root, '.git');
   if (!existsSync(gitDir)) return [];
 
@@ -886,10 +970,106 @@ function scanGitPrivacy(root) {
   if (result.status !== 0) return [];
 
   const tracked = result.stdout.split('\n').filter(Boolean);
-  return tracked.map((file) => ({
-    issue: `Git tracks private/local path: ${file}`,
-    fix: 'Untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
-  }));
+  return summarizeGitPrivacyIssues(tracked, config);
+}
+
+function summarizeGitPrivacyIssues(tracked, config) {
+  const grouped = new Map();
+  const singles = [];
+
+  for (const file of tracked) {
+    const root = gitPrivacyRoot(file);
+    if (!root) {
+      singles.push(file);
+      continue;
+    }
+    if (!grouped.has(root)) grouped.set(root, []);
+    grouped.get(root).push(file);
+  }
+
+  const issues = [];
+  const agentRootSummaries = [];
+
+  for (const file of singles.sort()) {
+    issues.push({
+      issue: `Git tracks private/local path: ${file}`,
+      fix: 'Untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
+    });
+  }
+
+  for (const root of Array.from(grouped.keys()).sort()) {
+    const files = grouped.get(root).slice().sort(compareGitPrivacyFiles);
+    if (GIT_PRIVACY_AGENT_ROOTS.has(root)) {
+      agentRootSummaries.push(`${root}/ (${files.length} files)`);
+      continue;
+    }
+    const samples = files.slice(0, 5);
+    const hiddenCount = files.length - samples.length;
+    const noun = files.length === 1 ? 'path' : 'paths';
+    const issue = `Git tracks private/local ${noun} under ${root}/ (${files.length} files)`;
+    const fix = 'Review the sample paths below. If the tree is intentionally tracked in this repo, keep it. Otherwise untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.';
+    const details = samples.map((file) => `sample: ${file}`);
+    if (hiddenCount > 0) {
+      details.push(`...and ${hiddenCount} more tracked paths`);
+    }
+    issues.push({ issue, fix, details });
+  }
+
+  if (agentRootSummaries.length) {
+    issues.unshift({
+      issue: `Tracked shared agent trees detected: ${agentRootSummaries.join(', ')}`,
+      fix: config.doctor.allowTrackedAgentTrees
+        ? undefined
+        : 'If these agent trees are intentionally versioned in this repo, keep them. Otherwise untrack them without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
+      details: [
+        config.doctor.allowTrackedAgentTrees
+          ? 'Allowed by `.nexus/config.json` because this repo intentionally versions shared agent trees.'
+          : 'This can be normal in private repos that share agent protocols and memory in Git.',
+      ],
+      ok: config.doctor.allowTrackedAgentTrees,
+    });
+  }
+
+  return issues;
+}
+
+function gitPrivacyRoot(file) {
+  for (const root of GIT_PRIVACY_COLLAPSE_ROOTS) {
+    if (matchesPrivatePath(file, root)) {
+      return root.replace(/\/$/, '');
+    }
+  }
+  return '';
+}
+
+function compareGitPrivacyFiles(a, b) {
+  return gitPrivacyPriority(a) - gitPrivacyPriority(b) || a.localeCompare(b);
+}
+
+function gitPrivacyPriority(file) {
+  if (/\/(CONTINUITY\.md|memories\/)/.test(file)) return 0;
+  if (/\/(AGENTS\.md|CLAUDE\.md|GEMINI\.md)$/.test(file)) return 1;
+  return 2;
+}
+
+function createColors() {
+  const enabled = supportsColor();
+  const wrap = (open, close) => (value) => enabled ? `\u001b[${open}m${value}\u001b[${close}m` : String(value);
+  return {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    cyan: wrap(36, 39),
+  };
+}
+
+function supportsColor() {
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
+  if ('NO_COLOR' in process.env) return false;
+  return Boolean(process.stdout && process.stdout.isTTY);
 }
 
 function scanGeneratedArtifacts(root) {

package/src/commands/init.js

@@ -379,6 +379,8 @@ This project uses Nexus for multi-agent coordination.
 ### Nexus Rules
 
 - Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
+- Nexus is agent-native and file-native, not feature-native: commit and release by file as soon as the file reaches a coherent checkpoint.
+- Do not hold claims while waiting to bundle related files into one feature commit; that blocks other agents who may need the file next.
 - Release finished work through Nexus: \`nexus release <path> "commit message"\`.
 - Use \`nexus next @Agent\` for the next safe queue task.
 - Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.

package/src/commands/status.js

@@ -7,6 +7,8 @@ import { listLocks } from '../lib/lockManager.js';
 import { getConfig } from '../lib/config.js';
 import { spawnSync } from 'child_process';
 
+const FILE_FLOW_WARNING = 'Stale claim. Commit this file now.';
+
 export default function status(args) {
   const config = getConfig();
   const locks = listLocks();
@@ -36,6 +38,9 @@ export default function status(args) {
     const staleTag = stale ? ' ⚠️  STALE' : '';
     console.log(`  🔒 ${lock.target}`);
     console.log(`     Agent: ${agent} | Age: ${ageStr}${staleTag}`);
+    if (stale) {
+      console.log(`     Warning: ${FILE_FLOW_WARNING}`);
+    }
   }
 
   console.log('');

package/src/lib/config.js

@@ -2,7 +2,7 @@
  * Config — resolve project root and Nexus paths
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { cwd } from 'process';
 
@@ -14,6 +14,7 @@ export function getConfig(fromDir) {
   const root = fromDir || cwd();
   const lockDir = join(root, '.nexus', 'locks');
   const budgetFile = join(root, '.nexus', 'agent-budgets.json');
+  const localConfig = readLocalConfig(root);
 
   _config = {
     root,
@@ -28,6 +29,9 @@ export function getConfig(fromDir) {
     maxDumpFiles: 20,
     maxClaimAttempts: 10,
     claimRetryMs: 2000,
+    doctor: {
+      allowTrackedAgentTrees: Boolean(localConfig.doctor?.allowTrackedAgentTrees),
+    },
   };
 
   return _config;
@@ -36,3 +40,15 @@ export function getConfig(fromDir) {
 export function resetConfig() {
   _config = null;
 }
+
+function readLocalConfig(root) {
+  const path = join(root, '.nexus', 'config.json');
+  if (!existsSync(path)) return {};
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}