@yemi33/minions 0.1.1893 → 0.1.1895

package/engine/cli.js

@@ -1144,7 +1144,8 @@ const commands = {
     const e = engine();
     if (!title) {
       console.log('Usage: node .minions/engine.js work "<title>" [options-json]');
-      console.log('Options: {"type":"implement","priority":"high","agent":"dallas","description":"...","branch":"feature/..."}');
+      console.log('Options: {"id":"W-customid","type":"implement","priority":"high","agent":"dallas","description":"...","branch":"feature/...","project":"minions"}');
+      console.log('  id  Optional caller-supplied work item ID. Defaults to a cuid-style W-<id>.');
       return;
     }
 
@@ -1157,7 +1158,7 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects, projectWorkItemsPath, resolveProjectSource } = require('./shared');
+    const { getProjects, projectWorkItemsPath, resolveProjectSource, uid, safeJsonArr } = require('./shared');
     const projects = getProjects(config);
     const target = opts.project ? resolveProjectSource(opts.project, projects, { allowCentral: false }) : null;
     if (target?.error) {
@@ -1166,10 +1167,36 @@ const commands = {
     }
     const targetProject = target?.project || (projects.length > 0 ? projects[0] : null);
     const wiPath = projectWorkItemsPath(targetProject);
+    const archivePath = wiPath.replace(/\.json$/, '-archive.json');
+
+    // Caller-supplied id: validate and pre-check live + archive for collisions
+    // BEFORE acquiring the work-items lock, so a rejection never mutates state.
+    let requestedId = null;
+    if (opts.id != null) {
+      if (typeof opts.id !== 'string' || !opts.id.trim()) {
+        console.log('Error: opts.id must be a non-empty string');
+        process.exit(1);
+      }
+      requestedId = opts.id.trim();
+      const liveItems = safeJsonArr(wiPath);
+      const archivedItems = safeJsonArr(archivePath);
+      if (liveItems.some(w => w?.id === requestedId) || archivedItems.some(w => w?.id === requestedId)) {
+        console.log(`Error: work item id "${requestedId}" already exists in ${path.basename(wiPath)} or its archive`);
+        process.exit(1);
+      }
+    }
+
     let item;
+    let collision = false;
     mutateWorkItems(wiPath, items => {
+      const id = requestedId || ('W-' + uid());
+      // Re-check inside the lock to close the TOCTOU race against other writers.
+      if (items.some(w => w?.id === id)) {
+        collision = true;
+        return items;
+      }
       item = {
-        id: `W${String(items.length + 1).padStart(3, '0')}`,
+        id,
         title: title,
         type: opts.type || 'implement',
         status: WI_STATUS.QUEUED,
@@ -1184,7 +1211,12 @@ const commands = {
       items.push(item);
     });
 
-    console.log(`Queued work item: ${item.id} — ${item.title} (project: ${targetProject.name || 'default'})`);
+    if (collision || !item) {
+      console.log(`Error: work item id collision detected for "${requestedId || 'auto-generated'}"`);
+      process.exit(1);
+    }
+
+    console.log(`Queued work item: ${item.id} — ${item.title} (project: ${targetProject?.name || 'default'})`);
     console.log(`  Type: ${item.type} | Priority: ${item.priority} | Agent: ${item.agent || 'auto'}`);
   },
 

package/engine/preflight.js

@@ -123,7 +123,7 @@ function _checkRuntimeBinary(runtimeName, { optional = false } = {}) {
     return {
       name: `Runtime: ${runtimeName}`,
       ok: false,
-      message: `unknown runtime — ${e.message}`,
+      message: `unknown runtime — ${e.message} (see docs/copilot-cli-schema.md)`,
     };
   }
   let resolved = null;
@@ -146,8 +146,8 @@ function _checkRuntimeBinary(runtimeName, { optional = false } = {}) {
     name: `Runtime: ${runtimeName}`,
     ok: optional ? 'warn' : false,
     message: optional
-      ? `not installed (optional) — ${hint}`
-      : `not found — ${hint}`,
+      ? `not installed (optional) — ${hint} (see docs/copilot-cli-schema.md)`
+      : `not found — ${hint} (see docs/copilot-cli-schema.md)`,
   };
 }
 
@@ -400,11 +400,11 @@ async function _modelDiscoveryResults(config) {
     catch { continue; /* unknown-cli warning was already emitted by runtimeConfigWarnings */ }
 
     if (fleetDisabled) {
-      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery disabled (engine.disableModelDiscovery)' });
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery disabled (engine.disableModelDiscovery) — see docs/copilot-cli-schema.md' });
       continue;
     }
     if (!adapter.capabilities || adapter.capabilities.modelDiscovery !== true) {
-      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (no enumeration mechanism)' });
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (no enumeration mechanism) — see docs/copilot-cli-schema.md' });
       continue;
     }
     try {
@@ -412,10 +412,10 @@ async function _modelDiscoveryResults(config) {
       if (Array.isArray(out.models) && out.models.length > 0) {
         results.push({ name: `Models: ${runtimeName}`, ok: true, message: `${out.models.length} models cached` });
       } else {
-        results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (API returned no models — check token)' });
+        results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (API returned no models — check token) — see docs/copilot-cli-schema.md' });
       }
     } catch (e) {
-      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: `discovery error — ${e && e.message ? e.message : 'unknown'}` });
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: `discovery error — ${e && e.message ? e.message : 'unknown'} (see docs/copilot-cli-schema.md)` });
     }
   }
   return results;
@@ -442,7 +442,7 @@ function doctor(minionsHome) {
   if (fs.existsSync(engineJs)) {
     runtimeResults.push({ name: 'Minions installed', ok: true, message: minionsHome });
   } else {
-    runtimeResults.push({ name: 'Minions installed', ok: false, message: `not found at ${minionsHome} — run: minions init` });
+    runtimeResults.push({ name: 'Minions installed', ok: false, message: `not found at ${minionsHome} — run: minions init (see docs/distribution.md)` });
   }
 
   // Check config.json
@@ -454,13 +454,13 @@ function doctor(minionsHome) {
     if (real.length > 0) {
       runtimeResults.push({ name: 'Projects configured', ok: true, message: `${real.length} project(s)` });
     } else {
-      runtimeResults.push({ name: 'Projects configured', ok: false, message: 'no projects — run: minions add <dir>' });
+      runtimeResults.push({ name: 'Projects configured', ok: false, message: 'no projects — run: minions add <dir> (see docs/auto-discovery.md)' });
     }
 
     // Check project paths exist
     for (const p of real) {
       if (p.localPath && !fs.existsSync(p.localPath)) {
-        runtimeResults.push({ name: `Project "${p.name}"`, ok: false, message: `path not found: ${p.localPath}` });
+        runtimeResults.push({ name: `Project "${p.name}"`, ok: false, message: `path not found: ${p.localPath} — fix config.json or re-run: minions add <dir> (see docs/auto-discovery.md)` });
       }
     }
 
@@ -469,7 +469,7 @@ function doctor(minionsHome) {
     if (Object.keys(agents).length > 0) {
       runtimeResults.push({ name: 'Agents configured', ok: true, message: `${Object.keys(agents).length} agent(s)` });
     } else {
-      runtimeResults.push({ name: 'Agents configured', ok: false, message: 'no agents in config.json' });
+      runtimeResults.push({ name: 'Agents configured', ok: false, message: 'no agents in config.json — re-run: minions init (see docs/auto-discovery.md)' });
     }
 
     // Check Teams integration — supports client secret OR certificate auth
@@ -482,7 +482,7 @@ function doctor(minionsHome) {
           !teams.appId && 'appId',
           !teams.appPassword && !teams.certPath && 'appPassword or certPath+privateKeyPath+tenantId',
         ].filter(Boolean).join(', ');
-        runtimeResults.push({ name: 'Teams integration', ok: 'warn', message: `enabled but missing: ${missing}` });
+        runtimeResults.push({ name: 'Teams integration', ok: 'warn', message: `enabled but missing: ${missing} — see docs/teams-setup.md` });
       } else {
         const authMode = hasCert ? 'certificate' : 'client secret';
         runtimeResults.push({ name: 'Teams integration', ok: true, message: `configured (${authMode})` });
@@ -491,7 +491,7 @@ function doctor(minionsHome) {
       runtimeResults.push({ name: 'Teams integration', ok: 'warn', message: 'disabled — see docs/teams-setup.md' });
     }
   } catch {
-    runtimeResults.push({ name: 'Config', ok: false, message: `missing or invalid — run: minions init` });
+    runtimeResults.push({ name: 'Config', ok: false, message: `missing or invalid — run: minions init (see docs/distribution.md)` });
   }
 
   // Check engine status
@@ -509,12 +509,12 @@ function doctor(minionsHome) {
           alive = true;
         }
       } catch { /* process may be dead */ }
-      runtimeResults.push({ name: 'Engine', ok: alive, message: alive ? `running (PID ${control.pid})` : `stale PID ${control.pid} — run: minions start` });
+      runtimeResults.push({ name: 'Engine', ok: alive, message: alive ? `running (PID ${control.pid})` : `stale PID ${control.pid} — run: minions start (see docs/engine-restart.md)` });
     } else {
-      runtimeResults.push({ name: 'Engine', ok: 'warn', message: `${control.state || 'stopped'} — run: minions start` });
+      runtimeResults.push({ name: 'Engine', ok: 'warn', message: `${control.state || 'stopped'} — run: minions start (see docs/engine-restart.md)` });
     }
   } catch {
-    runtimeResults.push({ name: 'Engine', ok: 'warn', message: 'not started — run: minions start' });
+    runtimeResults.push({ name: 'Engine', ok: 'warn', message: 'not started — run: minions start (see docs/engine-restart.md)' });
   }
 
   // Check dashboard (try HTTP)
@@ -523,8 +523,8 @@ function doctor(minionsHome) {
     const req = http.get('http://localhost:7331/api/health', { timeout: 2000 }, res => {
       resolve({ name: 'Dashboard', ok: true, message: 'running on http://localhost:7331' });
     });
-    req.on('error', () => resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash' }));
-    req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash' }); });
+    req.on('error', () => resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash (see docs/engine-restart.md)' }));
+    req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash (see docs/engine-restart.md)' }); });
   });
 
   return dashCheck.then(async dashResult => {
@@ -537,12 +537,12 @@ function doctor(minionsHome) {
     if (playbooks.length > 0) {
       runtimeResults.push({ name: 'Playbooks', ok: true, message: `${playbooks.length} playbooks found` });
     } else {
-      runtimeResults.push({ name: 'Playbooks', ok: false, message: 'no playbooks found in playbooks/ — run: minions init --force' });
+      runtimeResults.push({ name: 'Playbooks', ok: false, message: 'no playbooks found in playbooks/ — run: minions init --force (see docs/distribution.md)' });
     }
 
     // Check port 7331 availability (only if dashboard isn't running)
     if (dashResult.ok !== true) {
-      runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown' });
+      runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown (see docs/engine-restart.md)' });
     }
 
     // Fleet defaults + per-runtime model discovery (P-9e8a3f1d). Both depend

package/engine/shared.js

@@ -1716,7 +1716,7 @@ const ESCALATION_POLICY = {
 };
 
 // Structured completion protocol — fields agents must produce in ```completion blocks
-const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'pending', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts'];
+const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,

package/engine.js

@@ -1649,7 +1649,6 @@ async function spawnAgent(dispatchItem, config) {
       errorReason = structuredCompletion
         ? String(
             structuredCompletion.summary
-            || structuredCompletion.pending
             || structuredCompletion.failure_class
             || `Agent reported ${structuredCompletion.status || 'failure'}`
           ).slice(0, 300)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1893",
+  "version": "0.1.1895",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/shared-rules.md

@@ -67,7 +67,7 @@ Bias toward senior-engineer restraint:
 The engine provides a completion report path in the prompt and in `MINIONS_COMPLETION_REPORT`. Before exiting, write JSON there with the actual outcome:
 
 ```json
-{"status":"success","summary":"what changed and how it was validated","verdict":null,"pr":"PR id/url or N/A","failure_class":"N/A","retryable":false,"needs_rerun":false,"artifacts":[{"type":"note|plan|prd|pr|file","path":"relative/path/or/url","title":"short label"}]}
+{"status":"success","summary":"what changed and how it was validated","verdict":null,"pr":"PR id/url or N/A","failure_class":"N/A","retryable":false,"needs_rerun":false,"not_changed":"adjacent X left alone; refactor Y declined as out of scope","artifacts":[{"type":"note|plan|prd|pr|file","path":"relative/path/or/url","title":"short label"}]}
 ```
 
 For the canonical schema — every field, the `failure_class` enum, `noop:true` semantics, `retryable` / `needs_rerun` shape, and the artifacts array — see `docs/completion-reports.md`. The JSON report is the primary signal; fenced `completion` blocks in stdout are accepted only as a fallback.