@inkobytes/nexus 1.0.0

package/src/commands/ledger.js

@@ -0,0 +1,215 @@
+/**
+ * nexus ledger [--json]
+ * Read completed task ledger entries for dashboard/reporting.
+ */
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { getConfig } from '../lib/config.js';
+
+export default function ledger(args) {
+  if (args[0] === 'backfill') {
+    const count = backfillLedger();
+    console.log(`Backfilled ${count} completed task entr${count === 1 ? 'y' : 'ies'} into _NEXUS_LEDGER.md.`);
+    return;
+  }
+
+  const entries = readLedgerEntries();
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ entries, totals: buildTotals(entries) }, null, 2));
+    return;
+  }
+
+  console.log('Nexus ledger');
+  console.log('');
+  if (!entries.length) {
+    console.log('No completed task entries yet.');
+    return;
+  }
+
+  for (const entry of entries.slice().reverse().slice(0, 20)) {
+    console.log(`- ${entry.completedAt} ${entry.id} (${entry.agent})`);
+    console.log(`  ${entry.title}`);
+    console.log(`  Epic: ${entry.epic || 'unknown'} | Cost: ${entry.cost || 'unknown'}`);
+    if (entry.files.length) console.log(`  Files: ${entry.files.join(', ')}`);
+  }
+}
+
+export function appendCompletedLedgerEntries({ target, agent, sha, commit }) {
+  const config = getConfig();
+  const queueText = readText(config.queue);
+  const existingIds = new Set(readLedgerEntries().map((entry) => entry.id));
+  const tasks = parseQueueTasks(queueText)
+    .filter((task) => task.checked)
+    .filter((task) => task.id && !existingIds.has(task.id))
+    .filter((task) => task.files.includes(target))
+    .filter((task) => commitReferencesTask(commit, task.id));
+
+  if (!tasks.length) return 0;
+  ensureLedgerFile(config.ledger);
+
+  const completedAt = new Date().toISOString();
+  for (const task of tasks) {
+    appendFileSync(config.ledger, renderEntry({
+      ...task,
+      agent,
+      sha,
+      commit,
+      completedAt,
+    }), 'utf-8');
+  }
+
+  return tasks.length;
+}
+
+export function readLedgerEntries() {
+  const config = getConfig();
+  const content = readText(config.ledger);
+  const entries = [];
+  const blocks = content.split(/\n(?=## )/);
+
+  for (const block of blocks) {
+    const header = block.match(/^## ([^\n]+)$/m);
+    if (!header) continue;
+    entries.push({
+      id: readField(block, 'Id') || header[1].trim(),
+      title: readField(block, 'Title'),
+      agent: readField(block, 'Agent') || 'unknown',
+      epic: readField(block, 'Epic'),
+      cost: readField(block, 'Cost'),
+      completedAt: readField(block, 'Completed At'),
+      sha: readField(block, 'SHA'),
+      commit: readField(block, 'Commit'),
+      source: readField(block, 'Source') || 'release',
+      files: splitCsv(readField(block, 'Files')),
+    });
+  }
+
+  return entries;
+}
+
+export function backfillLedger() {
+  const config = getConfig();
+  const existingIds = new Set(readLedgerEntries().map((entry) => entry.id));
+  const tasks = parseQueueTasks(readText(config.queue))
+    .filter((task) => task.checked)
+    .filter((task) => task.id && !existingIds.has(task.id));
+
+  if (!tasks.length) return 0;
+  ensureLedgerFile(config.ledger);
+
+  const completedAt = new Date().toISOString();
+  for (const task of tasks) {
+    appendFileSync(config.ledger, renderEntry({
+      ...task,
+      agent: normalizeAgentForLedger(task.agent),
+      sha: 'unknown',
+      commit: `backfill: ${task.id}`,
+      completedAt,
+      source: 'backfill',
+    }), 'utf-8');
+  }
+
+  return tasks.length;
+}
+
+function buildTotals(entries) {
+  return {
+    completedTasks: entries.length,
+    byAgent: countBy(entries, 'agent'),
+    byEpic: countBy(entries, 'epic'),
+    byCost: countBy(entries, 'cost'),
+  };
+}
+
+function parseQueueTasks(content) {
+  const tasks = [];
+  const lines = content.split('\n');
+  let current = null;
+
+  for (const line of lines) {
+    const match = line.match(/^- \[([ x])\] TASK\/([^:]+):\s*(.+)$/);
+    if (match) {
+      if (current) tasks.push(current);
+      current = {
+        checked: match[1] === 'x',
+        agent: match[2].trim(),
+        title: match[3].trim(),
+        id: '',
+        epic: '',
+        files: [],
+        cost: '',
+      };
+      continue;
+    }
+
+    if (!current) continue;
+    const field = line.trim().match(/^- ([^:]+):\s*(.*)$/);
+    if (!field) continue;
+
+    const key = field[1].toLowerCase();
+    const value = field[2].trim();
+    if (key === 'id') current.id = value;
+    if (key === 'epic') current.epic = value;
+    if (key === 'files') current.files = splitCsv(value);
+    if (key === 'cost') current.cost = value;
+  }
+
+  if (current) tasks.push(current);
+  return tasks;
+}
+
+function ensureLedgerFile(path) {
+  if (existsSync(path)) return;
+  writeFileSync(path, '# Nexus Completed Task Ledger\n\n', 'utf-8');
+}
+
+function renderEntry(entry) {
+  return `## ${entry.id}
+
+- Id: ${entry.id}
+- Title: ${entry.title}
+- Agent: ${entry.agent || 'unknown'}
+- Epic: ${entry.epic || 'unknown'}
+- Cost: ${entry.cost || 'unknown'}
+- Completed At: ${entry.completedAt}
+- Files: ${entry.files.join(', ')}
+- SHA: ${entry.sha || 'unknown'}
+- Commit: ${entry.commit || ''}
+- Source: ${entry.source || 'release'}
+
+`;
+}
+
+function readText(path) {
+  if (!existsSync(path)) return '';
+  return readFileSync(path, 'utf-8');
+}
+
+function readField(block, label) {
+  return block.match(new RegExp(`^- ${label}: (.*)$`, 'm'))?.[1]?.trim() || '';
+}
+
+function splitCsv(value) {
+  if (!value) return [];
+  return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function commitReferencesTask(commit, taskId) {
+  const normalizedCommit = String(commit || '').toLowerCase();
+  return normalizedCommit.includes(taskId.toLowerCase());
+}
+
+function countBy(items, key) {
+  const counts = {};
+  for (const item of items) {
+    const value = item[key] || 'unknown';
+    counts[value] = (counts[value] || 0) + 1;
+  }
+  return counts;
+}
+
+function normalizeAgentForLedger(agent) {
+  const value = String(agent || '').trim();
+  return value.startsWith('@') ? value : `@${value.toLowerCase()}`;
+}

package/src/commands/metrics.js

@@ -0,0 +1,178 @@
+/**
+ * nexus metrics [--json]
+ * Read-only summary of Nexus release and queue activity.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { getConfig } from '../lib/config.js';
+
+export default function metrics(args) {
+  const json = args.includes('--json');
+  const config = getConfig();
+  const reportText = readText(config.report);
+  const queueText = readText(config.queue);
+  const gitCommits = readGitCommits(config.root);
+  const releases = parseReport(reportText);
+  const summary = buildSummary(gitCommits, releases, queueText);
+
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  printSummary(summary);
+}
+
+function readText(path) {
+  if (!existsSync(path)) return '';
+  return readFileSync(path, 'utf-8');
+}
+
+function readGitCommits(root) {
+  const result = spawnSync('git', ['log', '--date=short', '--pretty=format:%H%x09%ad%x09%s'], {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  });
+  if (result.status !== 0) return [];
+
+  return result.stdout.split('\n').filter(Boolean).map((line) => {
+    const [sha, date, ...subjectParts] = line.split('\t');
+    const subject = subjectParts.join('\t');
+    const match = subject.match(/^\[([^\]]+)\]\s+(.+)$/);
+    const rawAgent = match ? match[1] : '';
+    return {
+      sha,
+      date,
+      agent: normalizeAgentBucket(rawAgent),
+      subject: match ? match[2] : subject,
+    };
+  });
+}
+
+function parseReport(content) {
+  const releases = [];
+  const blocks = content.split(/\n(?=## \[\d\d:\d\d:\d\d\] )/);
+
+  for (const block of blocks) {
+    const header = block.match(/^## \[(\d\d:\d\d:\d\d)\] (.+)$/m);
+    if (!header) continue;
+    releases.push({
+      time: header[1],
+      target: readField(block, 'Target') || header[2],
+      agent: normalizeAgentBucket(readField(block, 'Agent')),
+      sha: readField(block, 'SHA') || '',
+      commit: readField(block, 'Commit') || '',
+    });
+  }
+
+  return releases;
+}
+
+function readField(block, label) {
+  return block.match(new RegExp(`^- ${label}: (.+)$`, 'm'))?.[1] || '';
+}
+
+function buildSummary(gitCommits, releases, queueText) {
+  return {
+    identityBuckets: {
+      'legacy-agent': 'Older Nexus releases used the generic [Agent] commit or report label before explicit handles shipped.',
+      'unknown-agent': 'No parseable agent label was found in the commit subject or report receipt.',
+    },
+    commitsByAgent: countBy(gitCommits, 'agent'),
+    releasesByAgent: countBy(releases, 'agent'),
+    topReleaseTargets: topCounts(countBy(releases, 'target'), 8),
+    weeklyVelocity: countBy(gitCommits, (commit) => weekKey(commit.date)),
+    queueCostDistribution: parseQueueCostDistribution(queueText),
+    totals: {
+      commits: gitCommits.length,
+      releases: releases.length,
+    },
+  };
+}
+
+function normalizeAgentBucket(agent) {
+  const value = String(agent || '').trim();
+  if (!value) return 'unknown-agent';
+  if (value.toLowerCase() === 'unknown') return 'unknown-agent';
+  if (value.toLowerCase() === 'agent') return 'legacy-agent';
+  return value;
+}
+
+function countBy(items, keyOrFn) {
+  const counts = {};
+  for (const item of items) {
+    const key = typeof keyOrFn === 'function' ? keyOrFn(item) : item[keyOrFn];
+    if (!key) continue;
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+function topCounts(counts, limit) {
+  return Object.entries(counts)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([name, count]) => ({ name, count }));
+}
+
+function weekKey(dateText) {
+  if (!dateText) return 'unknown';
+  const date = new Date(`${dateText}T00:00:00Z`);
+  if (Number.isNaN(date.getTime())) return 'unknown';
+  const day = date.getUTCDay() || 7;
+  date.setUTCDate(date.getUTCDate() - day + 1);
+  return date.toISOString().slice(0, 10);
+}
+
+function parseQueueCostDistribution(content) {
+  const counts = {};
+  for (const line of content.split('\n')) {
+    const match = line.trim().match(/^- Cost:\s*(.+)$/);
+    if (!match) continue;
+    const cost = match[1];
+    counts[cost] = (counts[cost] || 0) + 1;
+  }
+  return counts;
+}
+
+function printSummary(summary) {
+  console.log('Nexus metrics');
+  console.log('');
+  console.log(`Totals: ${summary.totals.commits} commits, ${summary.totals.releases} release receipt(s)`);
+  printCounts('Commits by agent', summary.commitsByAgent);
+  printCounts('Releases by agent', summary.releasesByAgent);
+  printIdentityNotes(summary);
+  printTopTargets(summary.topReleaseTargets);
+  printCounts('Weekly velocity', summary.weeklyVelocity);
+  printCounts('Queue cost distribution', summary.queueCostDistribution);
+}
+
+function printIdentityNotes(summary) {
+  const used = Object.keys(summary.identityBuckets)
+    .filter((bucket) => summary.commitsByAgent[bucket] || summary.releasesByAgent[bucket]);
+  if (!used.length) return;
+
+  console.log('\nIdentity bucket notes');
+  for (const bucket of used) console.log(`  ${bucket}: ${summary.identityBuckets[bucket]}`);
+}
+
+function printCounts(title, counts) {
+  console.log(`\n${title}`);
+  const rows = Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  if (!rows.length) {
+    console.log('  none');
+    return;
+  }
+  for (const [name, count] of rows) console.log(`  ${name}: ${count}`);
+}
+
+function printTopTargets(targets) {
+  console.log('\nTop release targets');
+  if (!targets.length) {
+    console.log('  none');
+    return;
+  }
+  for (const target of targets) console.log(`  ${target.name}: ${target.count}`);
+}

package/src/commands/next.js

@@ -0,0 +1,317 @@
+/**
+ * nexus next <agent>
+ * Budget-aware task suggestion from the ready queue.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { getConfig } from '../lib/config.js';
+import { readBoard } from '../lib/blackboard.js';
+import { spawnSync } from 'child_process';
+
+export default function next(args) {
+  const agent = args[0];
+
+  if (!agent) {
+    console.error('Usage: nexus next <agent_name>');
+    process.exit(1);
+  }
+
+  const config = getConfig();
+
+  // Read queue file
+  if (!existsSync(config.queue)) {
+    console.log('No _NEXUS_QUEUE.md found. Nothing to suggest.');
+    return;
+  }
+
+  const queueContent = readFileSync(config.queue, 'utf-8');
+  const boardContent = readBoard();
+
+  // Parse runway for this agent
+  const runway = parseRunway(queueContent, agent);
+
+  // Parse ready tasks
+  const tasks = parseReadyTasks(queueContent);
+
+  if (tasks.length === 0) {
+    console.log(`📋 No Ready tasks in queue. Standby.`);
+    return;
+  }
+
+  // Get currently claimed files from blackboard
+  const claimedFiles = parseClaimed(boardContent);
+
+  // Load budget if available
+  const budget = loadBudget(config.budgetFile, agent);
+
+  // Score and filter tasks — only Ready Queue, only human-approved auto-flow
+  const candidates = tasks
+    .filter(t => t.status === 'Ready')
+    .filter(t => t.autoFlow === 'yes')
+    .filter(t => t.review === 'approved')
+    .filter(t => !hasFileConflict(t.files, claimedFiles))
+    .filter(t => dependenciesMet(t.dependsOn, tasks, config.root))
+    .filter(t => t.cost !== 'spiky')
+    .filter(t => fitsbudget(t.cost, budget));
+
+  if (candidates.length === 0) {
+    console.log(`📋 No safe auto-flow tasks available for ${agent}. Standby.`);
+    return;
+  }
+
+  // Prefer same-runway, lower cost
+  const scored = candidates.map(t => ({
+    ...t,
+    score: scoreTask(t, runway),
+  })).sort((a, b) => b.score - a.score);
+
+  const pick = scored[0];
+  console.log(`\nNEXUS SUGGESTS for ${agent}:`);
+  console.log(`   Task: ${pick.id}`);
+  console.log(`   Epic: ${pick.epic}`);
+  console.log(`   Files: ${pick.files.join(', ')}`);
+  console.log(`   Cost: ${pick.cost}`);
+  console.log(`   Auto-flow: ${pick.autoFlow}`);
+  printRelatedDrills(pick);
+  console.log('');
+}
+
+const DATA_MUTATION_DRILL = `data-mutation-${'delete-rows'}`;
+
+const DRILL_GROUPS = [
+  {
+    group: 'data',
+    hints: [
+      { id: DATA_MUTATION_DRILL, keywords: ['db', 'database', 'migration', 'persisted'] },
+      { id: 'data-boundary-table-header', keywords: ['table header', 'table headers', 'columns', 'csv headers', 'schema'] },
+    ],
+  },
+  {
+    group: 'removal',
+    hints: [
+      { id: 'vendor-cleanup-preserve-history', keywords: ['payment vendor', 'audit log', 'audit logs', 'historical records', 'all traces'] },
+      { id: 'removal-scope', keywords: ['vendor', 'dependency', 'legacy integration', 'remove', 'cleanup'] },
+      { id: 'task-contract', keywords: ['completely', 'broad task', 'remove all', 'all traces', 'migration'] },
+    ],
+  },
+  {
+    group: 'publish',
+    hints: [
+      { id: 'private-path-protection', keywords: ['publish', 'npm', 'package', 'public', 'privacy', 'private'] },
+      { id: 'remove-agent-folders-from-git', keywords: ['untrack', 'gitignore', '.codex', '.claude', '.gemini', '.agy', '.nexus/local', 'user.md'] },
+    ],
+  },
+  {
+    group: 'git',
+    hints: [
+      { id: 'wrong-repo-push', keywords: ['push', 'remote', 'github', 'origin'] },
+      { id: 'stale-lock-after-commit', keywords: ['stale lock', 'stale locks', 'nexus clean', 'lock cleanup'] },
+    ],
+  },
+  {
+    group: 'protocol',
+    hints: [
+      { id: 'queue-is-thin-index', keywords: ['_nexus_queue.md', 'queue', 'task plan', 'handoff'] },
+      { id: 'current-file-state', keywords: ['current file', 'edited', 'existing file', 'stale context'] },
+      { id: 'ghost-file-claim-loop', keywords: ['pre-claim', 'claim loop', 'fresh file state'] },
+      { id: 'claim-before-edit', keywords: ['readme', 'docs', 'edit', 'update', 'modify'] },
+      { id: 'start-does-not-replace-claim-release', keywords: ['nexus start', 'start then edit'] },
+      { id: 'done-claim-adversarial', keywords: ['done', 'validated', 'verification', 'release'] },
+    ],
+  },
+];
+
+function printRelatedDrills(task) {
+  const drills = relatedDrillsForTask(task);
+  if (drills.length === 0) return;
+
+  console.log('');
+  console.log('   Related Drills:');
+  for (const id of drills) {
+    console.log(`   - ${id}`);
+  }
+  console.log('   Run `nexus drill show <id>` if the task matches that risk.');
+}
+
+function relatedDrillsForTask(task) {
+  if (task.drills.length > 0) return task.drills;
+
+  const haystack = [
+    task.title,
+    task.id,
+    task.epic,
+    task.dependsOn,
+    task.files.join(' '),
+    task.affinity.join(' '),
+    task.notes,
+  ].join(' ').toLowerCase();
+
+  const matches = [];
+  for (const group of DRILL_GROUPS) {
+    for (const hint of group.hints) {
+      if (hint.keywords.some(keyword => haystack.includes(keyword))) {
+        matches.push(hint.id);
+      }
+    }
+  }
+  return [...new Set(matches)];
+}
+
+function parseRunway(content, agent) {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    if (line.includes(agent) && line.includes('->')) {
+      return line
+        .split(':').slice(1).join(':')
+        .split('->')
+        .map(s => s.trim());
+    }
+  }
+  return [];
+}
+
+function extractSection(content, heading) {
+  const lines = content.split('\n');
+  let inSection = false;
+  const result = [];
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      inSection = line.trim() === heading;
+      continue;
+    }
+    if (inSection) result.push(line);
+  }
+  return result.join('\n');
+}
+
+function parseReadyTasks(content) {
+  // Only read from ## Ready Queue — Proposed section is invisible to nexus next
+  const sectionContent = extractSection(content, '## Ready Queue');
+  const tasks = [];
+  const lines = sectionContent.split('\n');
+  let current = null;
+
+  for (const line of lines) {
+    const taskMatch = line.match(/^- \[[ x]\] TASK\/.+?:\s*(.+)/);
+    if (taskMatch) {
+      if (current) tasks.push(current);
+      current = {
+        title: taskMatch[1],
+        id: '',
+        epic: '',
+        status: '',
+        dependsOn: '',
+        files: [],
+        affinity: [],
+        drills: [],
+        cost: 'medium',
+        autoFlow: 'no',
+        review: '',
+        approvedBy: '',
+        notes: '',
+      };
+      continue;
+    }
+
+    if (current && line.match(/^\s+-\s/)) {
+      const kv = line.trim().replace(/^-\s*/, '');
+      const colonIdx = kv.indexOf(':');
+      if (colonIdx === -1) continue;
+
+      const key = kv.slice(0, colonIdx).trim().toLowerCase();
+      const val = kv.slice(colonIdx + 1).trim();
+
+      switch (key) {
+        case 'id': current.id = val; break;
+        case 'epic': current.epic = val; break;
+        case 'status': current.status = val; break;
+        case 'depends on': current.dependsOn = val; break;
+        case 'files': current.files = val.split(',').map(s => s.trim()); break;
+        case 'affinity': current.affinity = val.split(',').map(s => s.trim()); break;
+        case 'drills': current.drills = val.split(',').map(s => s.trim()).filter(Boolean); break;
+        case 'cost': current.cost = val; break;
+        case 'auto-flow': current.autoFlow = val; break;
+        case 'review': current.review = val.toLowerCase(); break;
+        case 'approved by': current.approvedBy = val; break;
+        case 'notes': current.notes = val; break;
+      }
+    }
+  }
+
+  if (current) tasks.push(current);
+  return tasks;
+}
+
+function parseClaimed(boardContent) {
+  return boardContent
+    .split('\n')
+    .filter(l => l.includes('🔒'))
+    .map(l => {
+      const match = l.match(/\*\*(.+?)\*\*/);
+      return match ? match[1] : '';
+    })
+    .filter(Boolean);
+}
+
+function hasFileConflict(taskFiles, claimedFiles) {
+  for (const tf of taskFiles) {
+    for (const cf of claimedFiles) {
+      if (tf.startsWith(cf) || cf.startsWith(tf)) return true;
+    }
+  }
+  return false;
+}
+
+function dependenciesMet(dep, allTasks, root) {
+  if (!dep || dep === 'none') return true;
+
+  // Check if it's a task ID
+  const depTask = allTasks.find(t => t.id === dep);
+  if (depTask) return depTask.status === 'Done';
+
+  // Check if it's a git commit ref
+  const result = spawnSync('git', ['cat-file', '-t', dep], {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  });
+  return result.status === 0;
+}
+
+function fitsbudget(cost, budget) {
+  if (!budget) return true; // no budget file = no constraint
+
+  const costMap = { small: 5, medium: 15, large: 30, spiky: 50 };
+  const taskCost = costMap[cost] || 15;
+  const remaining = budget.session_budget - budget.used_session;
+
+  return taskCost <= remaining;
+}
+
+function loadBudget(budgetFile, agent) {
+  if (!existsSync(budgetFile)) return null;
+
+  try {
+    const data = JSON.parse(readFileSync(budgetFile, 'utf-8'));
+    return data[agent] || null;
+  } catch {
+    return null;
+  }
+}
+
+function scoreTask(task, runway) {
+  let score = 0;
+
+  // Runway position bonus (earlier = better)
+  const runwayIdx = runway.findIndex(r =>
+    task.epic.toLowerCase().includes(r.toLowerCase()) ||
+    r.toLowerCase().includes(task.epic.toLowerCase())
+  );
+  if (runwayIdx >= 0) score += (10 - runwayIdx);
+
+  // Cost preference (smaller = safer)
+  const costScore = { small: 3, medium: 2, large: 1, spiky: 0 };
+  score += costScore[task.cost] || 0;
+
+  return score;
+}