@inkobytes/nexus 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.6 - 2026-06-03
+
+- Extended Nexus protocol drift checks so `nexus doctor` now covers the bundled `skills/nexus/SKILL.md`.
+- Kept Nexus repo docs aligned with the agent-native release model while scoping root `README.md` doctor repair to the actual `@inkobytes/nexus` product repo.
+- Added regression coverage for Nexus-product README repair and for avoiding root README mutation in ordinary consumer repos.
+
+## 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.

package/README.md

@@ -389,11 +389,13 @@ Nexus reads tasks from `_NEXUS_QUEUE.md`:
   - Affinity: cli, diagnostics
   - Cost: small
   - Auto-flow: yes
+  - Review: approved
+  - Approved by: human
   - Notes: Add a doctor section for stale locks with tests and clear fix guidance.
 ```
 
 The queue is the executable priority surface. Standup is for comms and human context.
-Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.
+Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.
 
 Add `Drills` when a task has known failure-mode guidance:
 
@@ -408,12 +410,13 @@ When `Drills` is absent, `nexus next` may surface obvious related drills from ta
 The agent rule of thumb:
 
 1. Run `nexus start` when entering an existing repo; it does not replace claim/release.
-2. Read `USER.md` when present.
-3. Read continuity and latest memory when present.
-4. Read `_NEXUS_QUEUE.md` before taking follow-on work.
-5. Claim before touching shared project files.
-6. Release when finished.
-7. Use `nexus next @Agent` instead of free-roaming.
+2. Read `_NEXUS_CONSTITUTION.md`.
+3. Read `USER.md` when present.
+4. Read continuity and latest memory when present.
+5. Read `_NEXUS_QUEUE.md` before taking follow-on work.
+6. Claim before touching shared project files.
+7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.
+8. Use `nexus next @Agent` instead of free-roaming.
 
 Use model names as lock handles so ownership stays clear:
 
@@ -424,6 +427,8 @@ Use model names as lock handles so ownership stays clear:
 
 Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.
 
+Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.
+
 When a lead agent uses subagents, tools, or parallel workers, the lead still owns the repo effects. Claim the full path scope before delegating shared-file work, give subagents the claimed path and boundaries, re-read affected files before release, and mention delegated work when it changed files, tests, or risk.
 
 Supply-chain rule: agents should not install third-party packages that have existed for less than 14 days. If package age cannot be verified, stop and ask the human. `nexus doctor` also flags install hooks and package scripts that look like they could exfiltrate data.
@@ -445,7 +450,7 @@ Avoid introducing extra startup names in scripts or narration.
 
 Nexus ships an agent skill at `skills/nexus/SKILL.md`.
 
-The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.
+The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.
 
 ## Legacy Helper Transition
 

package/package.json

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

package/skills/nexus/SKILL.md

@@ -10,24 +10,27 @@ Nexus CLI is the coordination engine. This skill is only the agent playbook.
 ## Loop
 
 1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.
-2. Read `USER.md` if present for local user preferences.
-3. Read continuity and latest memory when present.
-4. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.
-5. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.
-6. Claim exact shared files before reading/editing:
+2. Read `_NEXUS_CONSTITUTION.md`.
+3. Read `USER.md` if present for local user preferences.
+4. Read continuity and latest memory when present.
+5. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.
+6. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.
+7. Claim exact shared files before reading/editing:
 
    ```bash
    nexus claim <path> @Agent "intent"
    ```
 
-7. Treat claim output as current file state. Ignore cached file memory when contents matter.
-8. Work only inside the claimed surface and run focused validation.
-9. If the user wants a commit, release through Nexus:
+8. Treat claim output as current file state. Ignore cached file memory when contents matter.
+9. Work only inside the claimed surface and run focused validation.
+10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:
 
    ```bash
    nexus release <path> "short commit message"
    ```
 
+11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.
+
 ## Queue Items
 
 When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immediately actionable. Use this shape:
@@ -42,12 +45,15 @@ When adding work to `_NEXUS_QUEUE.md`, keep tasks dashboard-parseable and immedi
   - Affinity: cli, docs, dashboard
   - Cost: small
   - Auto-flow: yes
+  - Review: approved
+  - Approved by: human
   - Notes: One practical paragraph with scope, constraints, and definition of done.
 ```
 
 - `Files` should name the likely edit surface so other agents can spot conflicts before claiming.
 - `Depends on` should list hard blockers by `Id`; use `none` when the task is independent.
 - `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.
+- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.
 - `Notes` should carry dashboard-useful context, not a whole design doc.
 
 ## Guardrails

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.
@@ -351,6 +352,7 @@ export default function doctor(args) {
   const sections = {
     'Nexus Files': [],
     'Agent Instructions': [],
+    'Docs & Skills': [],
     Security: [],
     'Package Privacy': [],
     'Git Privacy': [],
@@ -512,6 +514,37 @@ export default function doctor(args) {
     }
   }
 
+  const protocolDocs = [];
+  if (isNexusProductRepo(root)) {
+    protocolDocs.push({
+      path: 'README.md',
+      label: 'README.md',
+      repair: repairReadmeProtocolDoc,
+    });
+  }
+  protocolDocs.push({
+    path: 'skills/nexus/SKILL.md',
+    label: 'skills/nexus/SKILL.md',
+    repair: repairNexusSkillDoc,
+  });
+
+  for (const doc of protocolDocs) {
+    const path = join(root, doc.path);
+    if (!existsSync(path)) continue;
+    const existing = readFileSync(path, 'utf-8');
+    const next = doc.repair(existing);
+    if (next === existing) continue;
+    if (fix) {
+      writeFileSync(path, next, 'utf-8');
+      changes.push(`updated ${doc.label}`);
+    } else {
+      sections['Docs & Skills'].push({
+        issue: `${doc.label} is out of sync with current Nexus protocol wording`,
+        fix: 'Run `nexus doctor --fix`.',
+      });
+    }
+  }
+
   const locks = listLocks();
   const staleLocks = locks.filter((lock) => lock.age !== null && lock.age >= config.staleThreshold);
   const freshLocks = locks.filter((lock) => lock.age === null || lock.age < config.staleThreshold);
@@ -946,6 +979,140 @@ function replaceLegacyHelperCommands(content) {
     .join('\n');
 }
 
+function isNexusProductRepo(root) {
+  const packagePath = join(root, 'package.json');
+  if (!existsSync(packagePath)) return false;
+
+  try {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+    return pkg?.name === '@inkobytes/nexus';
+  } catch {
+    return false;
+  }
+}
+
+function repairReadmeProtocolDoc(content) {
+  return content
+    .replace(
+      [
+        '- [ ] TASK/Codex: Add doctor stale-lock category',
+        '  - Id: doctor-stale-locks',
+        '  - Epic: Release hygiene',
+        '  - Status: Ready',
+        '  - Depends on: none',
+        '  - Files: src/commands/doctor.js',
+        '  - Affinity: cli, diagnostics',
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
+      ].join('\n'),
+      [
+        '- [ ] TASK/Codex: Add doctor stale-lock category',
+        '  - Id: doctor-stale-locks',
+        '  - Epic: Release hygiene',
+        '  - Status: Ready',
+        '  - Depends on: none',
+        '  - Files: src/commands/doctor.js',
+        '  - Affinity: cli, diagnostics',
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Review: approved',
+        '  - Approved by: human',
+        '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
+      ].join('\n'),
+    )
+    .replace(
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.',
+    )
+    .replace(
+      [
+        '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
+        '2. Read `USER.md` when present.',
+        '3. Read continuity and latest memory when present.',
+        '4. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
+        '5. Claim before touching shared project files.',
+        '6. Release when finished.',
+        '7. Use `nexus next @Agent` instead of free-roaming.',
+      ].join('\n'),
+      [
+        '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
+        '2. Read `_NEXUS_CONSTITUTION.md`.',
+        '3. Read `USER.md` when present.',
+        '4. Read continuity and latest memory when present.',
+        '5. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
+        '6. Claim before touching shared project files.',
+        '7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.',
+        '8. Use `nexus next @Agent` instead of free-roaming.',
+      ].join('\n'),
+    )
+    .replace(
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\nNexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.',
+    )
+    .replace(
+      'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.',
+      'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.',
+    );
+}
+
+function repairNexusSkillDoc(content) {
+  return content
+    .replace(
+      [
+        '1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.',
+        '2. Read `USER.md` if present for local user preferences.',
+        '3. Read continuity and latest memory when present.',
+        '4. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.',
+        '5. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.',
+        '6. Claim exact shared files before reading/editing:',
+      ].join('\n'),
+      [
+        '1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.',
+        '2. Read `_NEXUS_CONSTITUTION.md`.',
+        '3. Read `USER.md` if present for local user preferences.',
+        '4. Read continuity and latest memory when present.',
+        '5. Read `_NEXUS_QUEUE.md` and `_NEXUS_STANDUP.md`.',
+        '6. Choose user-assigned work or `nexus next @Agent`; do not free-roam into `Auto-flow: no`.',
+        '7. Claim exact shared files before reading/editing:',
+      ].join('\n'),
+    )
+    .replace(
+      [
+        '7. Treat claim output as current file state. Ignore cached file memory when contents matter.',
+        '8. Work only inside the claimed surface and run focused validation.',
+        '9. If the user wants a commit, release through Nexus:',
+      ].join('\n'),
+      [
+        '8. Treat claim output as current file state. Ignore cached file memory when contents matter.',
+        '9. Work only inside the claimed surface and run focused validation.',
+        '10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
+      ].join('\n'),
+    )
+    .replace(
+      '```\\n\\n## Queue Items',
+      '```\\n\\n11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
+    )
+    .replace(
+      [
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Notes: One practical paragraph with scope, constraints, and definition of done.',
+      ].join('\n'),
+      [
+        '  - Cost: small',
+        '  - Auto-flow: yes',
+        '  - Review: approved',
+        '  - Approved by: human',
+        '  - Notes: One practical paragraph with scope, constraints, and definition of done.',
+      ].join('\n'),
+    )
+    .replace(
+      '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
+      '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
+    );
+}
+
 const SUSPICIOUS_SCRIPT_PATTERNS = [
   { pattern: /\b(curl|wget)\b/i, label: 'network download command' },
   { pattern: /\b(nc|netcat|ncat|socat)\b/i, label: 'raw network transfer command' },

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.