@inkobytes/nexus 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,12 +1,19 @@
 # Changelog
 
-## 1.0.3 - 2026-06-03
+## 1.0.5 - 2026-06-03
+
+- Reframed doctor-managed agent guides around agent-native, file-native release flow instead of human-oriented feature commit bundling.
+- Updated `nexus doctor --fix` and `nexus init` scaffolds to teach release-by-file at coherent checkpoints.
+- Added regression coverage so scaffold generation and repair keep the new agent-native wording stable.
+
+## 1.0.4 - 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.
+- Reformatted lock and queue findings into compact field-style output like `file`, `by`, `needs`, `impact`, and shorter `fix` lines.
 
 ## 1.0.1 - 2026-06-02
 

package/package.json

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

package/src/commands/doctor.js

@@ -93,8 +93,9 @@ 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.
+- Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics.
+- Release each claimed file as soon as it reaches a coherent checkpoint.
+- Never hold claims just to bundle a prettier feature commit; that blocks other agents.
 - 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.
@@ -521,6 +522,13 @@ export default function doctor(args) {
       sections.Locks.push({
         issue: `Stale lock on ${lock.target} (${lock.age}s old)`,
         fix: 'Run `nexus clean --stale`.',
+        displayGroup: lock.target,
+        lockInfo: {
+          target: lock.target,
+          agent: lock.agent || '',
+          kind: 'stale',
+          age: `${lock.age}s old`,
+        },
       });
     }
   }
@@ -532,18 +540,38 @@ export default function doctor(args) {
         issue: `Active lock on ${lock.target} (${age})`,
         fix: 'No action if the agent is still working. Use `nexus status` to inspect.',
         ok: true,
+        displayGroup: lock.target,
+        lockInfo: {
+          target: lock.target,
+          agent: lock.agent || '',
+          kind: 'active',
+          age,
+        },
       });
       if (!lock.model) {
         sections.Locks.push({
           issue: `Active lock on ${lock.target} has no --model metadata`,
           fix: 'Use `nexus claim ... --model <name>` for future claims; only the human operator can declare the real model.',
           ok: true,
+          displayGroup: lock.target,
+          lockInfo: {
+            target: lock.target,
+            agent: lock.agent || '',
+            kind: 'missing_model',
+          },
         });
       }
       if (!lock.verified) {
         sections.Locks.push({
           issue: `Unverified claim on ${lock.target} by ${lock.agent} (trust: ${lock.trustSource}) — no CLAUDECODE or NEXUS_AGENT env detected at claim time`,
           fix: 'If this is a local/unverified model, set NEXUS_AGENT=@handle before claiming. If unexpected, inspect the lock.',
+          displayGroup: lock.target,
+          lockInfo: {
+            target: lock.target,
+            agent: lock.agent || '',
+            kind: 'unverified',
+            trustSource: lock.trustSource,
+          },
         });
       }
     }
@@ -612,8 +640,15 @@ export default function doctor(args) {
     if (unapproved.length) {
       for (const id of unapproved) {
         sections['Queue Authorship'].push({
-          issue: `Task "${id}" is auto-flow: yes in Ready Queue but missing Review: approved — nexus next will skip it`,
-          fix: 'Add "- Review: approved" and "- Approved by: human" to the task, or move it to ## Proposed Queue.',
+          issue: `Task "${id}" is missing Review: approved`,
+          fix: 'add `Review: approved` and `Approved by: human`, or move it to `## Proposed Queue`',
+          displayGroup: id,
+          queueInfo: {
+            taskId: id,
+            state: 'auto-flow: yes in Ready Queue',
+            needs: 'Review: approved',
+            impact: 'nexus next will skip it',
+          },
         });
       }
     } else {
@@ -693,6 +728,14 @@ export default function doctor(args) {
 
 function renderEntryBucket(label, entries, headingColor, markerColor, sectionTitle, colors) {
   console.log(`  ${headingColor(label)}`);
+  if (sectionTitle === 'Locks') {
+    renderLockEntries(entries, markerColor, colors);
+    return;
+  }
+  if (sectionTitle === 'Queue Authorship') {
+    renderQueueEntries(entries, markerColor, colors);
+    return;
+  }
   const groups = groupEntriesForDisplay(entries, sectionTitle);
   for (const group of groups) {
     if (group.label) {
@@ -715,6 +758,96 @@ function renderEntryBucket(label, entries, headingColor, markerColor, sectionTit
   }
 }
 
+function renderLockEntries(entries, markerColor, colors) {
+  const groups = new Map();
+
+  for (const entry of entries) {
+    const target = entry.lockInfo?.target || entry.displayGroup || entry.issue;
+    if (!groups.has(target)) groups.set(target, []);
+    groups.get(target).push(entry);
+  }
+
+  for (const [target, lockEntries] of groups) {
+    const agent = lockEntries.find((entry) => entry.lockInfo?.agent)?.lockInfo?.agent || '';
+    console.log(`    ${colors.bold(`file: ${target}`)}`);
+    console.log(`      ${colors.dim(`by: ${agent || 'unknown'}`)}`);
+    for (const entry of lockEntries) {
+      const prefix = entry.ok ? '-' : '!';
+      const state = formatLockState(entry);
+      console.log(`      ${markerColor(prefix)} ${state}`);
+      if (entry.fix) {
+        console.log(`        ${colors.bold('fix:')} ${colors.dim(compactLockFix(entry))}`);
+      }
+    }
+  }
+}
+
+function renderQueueEntries(entries, markerColor, colors) {
+  const groups = new Map();
+
+  for (const entry of entries) {
+    const taskId = entry.queueInfo?.taskId || entry.displayGroup || entry.issue;
+    if (!groups.has(taskId)) groups.set(taskId, []);
+    groups.get(taskId).push(entry);
+  }
+
+  for (const [taskId, taskEntries] of groups) {
+    console.log(`    ${colors.bold(`task: ${taskId}`)}`);
+    for (const entry of taskEntries) {
+      const prefix = entry.ok ? '-' : '!';
+      const state = entry.queueInfo?.state || entry.issue;
+      const needs = entry.queueInfo?.needs;
+      const impact = entry.queueInfo?.impact;
+      console.log(`      ${markerColor(prefix)} ${state}`);
+      if (needs) {
+        console.log(`        ${colors.dim(`needs: ${needs}`)}`);
+      }
+      if (impact) {
+        console.log(`        ${colors.dim(`impact: ${impact}`)}`);
+      }
+      if (entry.fix) {
+        console.log(`        ${colors.bold('fix:')} ${colors.dim(entry.fix)}`);
+      }
+    }
+  }
+}
+
+function formatLockState(entry) {
+  const info = entry.lockInfo;
+  if (!info) return entry.issue;
+
+  switch (info.kind) {
+    case 'stale':
+      return `stale lock (${info.age})`;
+    case 'active':
+      return `active lock (${info.age})`;
+    case 'missing_model':
+      return 'missing --model metadata';
+    case 'unverified':
+      return `unverified claim (trust: ${info.trustSource || 'unknown'})`;
+    default:
+      return entry.issue;
+  }
+}
+
+function compactLockFix(entry) {
+  const info = entry.lockInfo;
+  if (!info) return entry.fix;
+
+  switch (info.kind) {
+    case 'stale':
+      return 'run `nexus clean --stale`';
+    case 'active':
+      return 'leave it if someone is working, or inspect with `nexus status`';
+    case 'missing_model':
+      return 'use `nexus claim ... --model <name>` on future claims';
+    case 'unverified':
+      return 'set `NEXUS_AGENT=@handle` for local claims, or inspect the lock';
+    default:
+      return entry.fix;
+  }
+}
+
 function groupEntriesForDisplay(entries, sectionTitle) {
   const groups = [];
   const grouped = new Map();

package/src/commands/init.js

@@ -379,8 +379,9 @@ 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.
+- Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics.
+- Release each claimed file as soon as it reaches a coherent checkpoint.
+- Never hold claims just to bundle a prettier feature commit; that blocks other agents.
 - 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.