@yemi33/minions 0.1.1810 → 0.1.1812

package/engine.js

@@ -592,7 +592,7 @@ async function spawnAgent(dispatchItem, config) {
   // Resolve prompt — prefers sidecar file when dispatchItem._promptFile is set
   // (large prompts are written to engine/contexts/<id>.md to keep dispatch.json
   // small — see shared.sidecarDispatchPrompt / #1167).
-  const taskPrompt = shared.resolveDispatchPrompt(dispatchItem);
+  let taskPrompt = shared.resolveDispatchPrompt(dispatchItem);
   const claudeConfig = config.claude || {};
   const engineConfig = config.engine || {};
   const startedAt = ts();
@@ -601,15 +601,16 @@ async function spawnAgent(dispatchItem, config) {
 
   // Resolve project context for this dispatch
   // meta.project has {name, localPath} — enrich with full config (mainBranch, repoHost, etc.)
-  const metaProject = meta?.project || {};
+  const metaProject = meta?.project;
   const projects = getProjects(config);
-  const fullProject = shared.findProjectByNameOrPath(projects, metaProject.name || metaProject.localPath);
-  if ((metaProject.name || metaProject.localPath) && !fullProject) {
-    const err = new Error(shared.formatUnknownProjectError(metaProject.name || metaProject.localPath, projects));
+  const projectResolution = shared.resolveConfiguredProject(metaProject, projects, { defaultWhenSingle: true });
+  if (projectResolution.error) {
+    const err = new Error(projectResolution.error);
     updateAgentStatus(id, AGENT_STATUS.FAILED, err.message);
     throw err;
   }
-  const project = fullProject ? { ...fullProject, ...metaProject } : (projects.length === 1 && !(metaProject.name || metaProject.localPath) ? projects[0] : {});
+  const metaProjectFields = metaProject && typeof metaProject === 'object' ? metaProject : {};
+  const project = projectResolution.project ? { ...projectResolution.project, ...metaProjectFields } : {};
   const rootDir = project.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
 
   // Determine working directory
@@ -621,8 +622,8 @@ async function spawnAgent(dispatchItem, config) {
   const _gitOpts = { stdio: 'pipe', timeout: 30000, windowsHide: true, env: shared.gitEnv() };
   const _worktreeGitOpts = { ..._gitOpts, timeout: worktreeCreateTimeout };
 
-  // Build prompt before worktree setup — prompt doesn't depend on worktree path
-  // and this avoids blocking 200ms of file reads behind 20-60s of git operations
+  // Build the initial prompt before worktree setup, then refresh shared-branch
+  // work-item prompts after setup because reused worktrees can live at arbitrary paths.
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
   const pendingSteering = steering.buildPendingSteeringPrompt(agentId);
@@ -642,15 +643,18 @@ async function spawnAgent(dispatchItem, config) {
     'This report is the primary completion signal; fenced completion blocks are only a fallback.',
     '',
   ].join('\n') : '';
-  const taskPromptWithSteering = pendingSteering.prompt
-    ? `${pendingSteering.prompt}\n\n---\n\n${taskPrompt}`
-    : taskPrompt;
-  const taskPromptWithReport = completionReportInstruction
-    ? `${taskPromptWithSteering}\n\n---\n\n${completionReportInstruction}`
-    : taskPromptWithSteering;
-  const fullTaskPrompt = agentContext
-    ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPromptWithReport}`
-    : taskPromptWithReport;
+  const buildFullTaskPrompt = (promptBody) => {
+    const taskPromptWithSteering = pendingSteering.prompt
+      ? `${pendingSteering.prompt}\n\n---\n\n${promptBody}`
+      : promptBody;
+    const taskPromptWithReport = completionReportInstruction
+      ? `${taskPromptWithSteering}\n\n---\n\n${completionReportInstruction}`
+      : taskPromptWithSteering;
+    return agentContext
+      ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPromptWithReport}`
+      : taskPromptWithReport;
+  };
+  let fullTaskPrompt = buildFullTaskPrompt(taskPrompt);
   const tmpDir = path.join(ENGINE_DIR, 'tmp');
   if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
   const safeId = id.replace(/[:\\/*?"<>|]/g, '-');
@@ -1064,6 +1068,25 @@ async function spawnAgent(dispatchItem, config) {
 
   updateAgentStatus(id, AGENT_STATUS.READY, 'Worktree ready, preparing to spawn process');
 
+  if (worktreePath && meta?.source === 'work-item' && meta?.item?.branchStrategy === 'shared-branch') {
+    const refreshed = renderProjectWorkItemPromptForAgent(
+      meta.item,
+      routing.normalizeWorkType(type, WORK_TYPE.IMPLEMENT),
+      agentId,
+      config,
+      project,
+      rootDir,
+      branchName,
+      { worktreePath }
+    );
+    if (refreshed.prompt) {
+      taskPrompt = refreshed.prompt;
+      fullTaskPrompt = buildFullTaskPrompt(taskPrompt);
+      safeWrite(promptPath, fullTaskPrompt);
+      log('info', `Refreshed shared-branch prompt for ${id} with worktree ${worktreePath}`);
+    }
+  }
+
   // Inject dirty file list when worktree has uncommitted changes (e.g., max_turns retry)
   // This signals to the respawned agent that prior work exists in the worktree (#960)
   if (worktreePath && fs.existsSync(worktreePath)) {
@@ -1714,7 +1737,7 @@ async function spawnAgent(dispatchItem, config) {
     }
   }, 5000);
 
-  // Move pending -> active under a lock to avoid cross-process lost updates (engine/dashboard)
+  // Move pending -> active under lock to avoid lost updates.
   mutateDispatch((dispatch) => {
     const idx = dispatch.pending.findIndex(d => d.id === id);
     if (idx < 0) return dispatch;
@@ -1736,9 +1759,7 @@ async function spawnAgent(dispatchItem, config) {
   // reads dispatchItem.started_at for runtimeMs. (W-moux9nwn0008f923)
   dispatchItem.started_at = startedAt;
 
-  // Atomically stamp dispatched_to/dispatched_at on the originating work item (#402)
-  // The discover phase sets these via safeWrite which can race with concurrent writes;
-  // this locked write ensures the fields are persisted reliably.
+  // Atomically stamp dispatched_to/dispatched_at on the originating work item (#402).
   if (meta?.item?.id) {
     try {
       let wiPath = null;
@@ -2248,7 +2269,7 @@ function materializePlansAsWorkItems(config) {
 
     const defaultProjectName = plan.project || file.replace(/-\d{4}-\d{2}-\d{2}\.json$/, '');
     const allProjects = getProjects(config);
-    const defaultProject = allProjects.find(p => p.name?.toLowerCase() === defaultProjectName.toLowerCase());
+    const defaultProject = shared.resolveProjectSource(defaultProjectName, allProjects, { allowCentral: false }).project;
     // No project found — use central work-items.json (engine works without projects)
     const useCentral = !defaultProject;
 
@@ -2268,7 +2289,7 @@ function materializePlansAsWorkItems(config) {
     const itemsByProject = new Map(); // projectName -> { project, items: [] }
     for (const item of items) {
       if (item.project) {
-        const itemProject = allProjects.find(p => p.name?.toLowerCase() === String(item.project).toLowerCase());
+        const itemProject = shared.resolveProjectSource(item.project, allProjects, { allowCentral: false }).project;
         if (!itemProject) {
           const error = shared.formatUnknownProjectError(item.project, allProjects);
           log('warn', `PRD ${file} item ${item.id || item.name}: ${error}`);
@@ -2288,7 +2309,7 @@ function materializePlansAsWorkItems(config) {
         itemsByProject.get('_central').items.push(item);
       } else {
         const itemProjectName = defaultProjectName;
-        const itemProject = allProjects.find(p => p.name?.toLowerCase() === itemProjectName.toLowerCase()) || defaultProject;
+        const itemProject = shared.resolveProjectSource(itemProjectName, allProjects, { allowCentral: false }).project || defaultProject;
         if (!itemProject) continue;
         if (!itemsByProject.has(itemProject.name)) {
           itemsByProject.set(itemProject.name, { project: itemProject, items: [] });
@@ -2333,7 +2354,7 @@ function materializePlansAsWorkItems(config) {
           let alreadyExists = !!existingWi;
           if (!alreadyExists) {
             for (const p of allProjects) {
-              if (p.name === projName) continue;
+              if (String(p.name || '').toLowerCase() === String(projName || '').toLowerCase()) continue;
               const otherItems = safeJson(projectWorkItemsPath(p)) || [];
               const otherWi = otherItems.find(w => w.id === item.id);
               if (otherWi) {
@@ -2399,7 +2420,7 @@ function materializePlansAsWorkItems(config) {
 
       // Process cross-project re-opens outside the lock (no nested locks)
       for (const { itemId, projectName: rProjName, item: rItem } of deferredReopens) {
-        const rProject = allProjects.find(p => p.name === rProjName);
+        const rProject = shared.resolveProjectSource(rProjName, allProjects, { allowCentral: false }).project;
         if (!rProject) continue;
         const rPath = projectWorkItemsPath(rProject);
         mutateWorkItems(rPath, items => {
@@ -2631,7 +2652,7 @@ function isPrAutomationCausePending(project, pr, causeKey) {
     if (d.meta?.automationCauseKey !== causeKey) return false;
     if (!prCanonicalId) return true;
     const dispatchProject = d.meta?.project?.name
-      ? (getProjects(getConfig()).find(p => p.name === d.meta.project.name) || d.meta.project)
+      ? (shared.resolveProjectSource(d.meta.project.name, getProjects(getConfig()), { allowCentral: false }).project || d.meta.project)
       : (d.meta?.project || null);
     const dispatchPrId = shared.getCanonicalPrId(dispatchProject, d.meta?.pr, d.meta?.pr?.url || '');
     return !dispatchPrId || dispatchPrId === prCanonicalId;
@@ -2678,8 +2699,6 @@ async function discoverFromPrs(config, project) {
   const newWork = [];
 
   const projMeta = { name: project?.name, localPath: project?.localPath };
-  const projectsByName = new Map(shared.getProjects(config).map(p => [p.name, p]));
-
   // Resolve poll-enabled per project — stale reviewStatus is untrustworthy without poller
   const isAdoProject = project?.repoHost !== 'github';
   const pollEnabled = isAdoProject
@@ -2699,7 +2718,7 @@ async function discoverFromPrs(config, project) {
       .filter(d => d.meta?.pr?.id)
       .map(d => {
         const dispatchProject = d.meta?.project?.name
-          ? (projectsByName.get(d.meta.project.name) || d.meta.project)
+          ? (shared.resolveProjectSource(d.meta.project.name, shared.getProjects(config), { allowCentral: false }).project || d.meta.project)
           : (d.meta?.project || null);
         return shared.getCanonicalPrId(dispatchProject, d.meta.pr, d.meta.pr?.url || '');
       })
@@ -3074,7 +3093,8 @@ async function discoverFromPrs(config, project) {
 /**
  * Scan work-items.json for manually queued tasks
  */
-function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, project, root, branchName) {
+function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, project, root, branchName, options = {}) {
+  const worktreePath = options.worktreePath || path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`);
   const vars = {
     ...buildBaseVars(agentId, config, project),
     item_id: item.id,
@@ -3091,7 +3111,7 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     scope_section: `## Scope: Project — ${project?.name || 'default'}\n\nThis task is scoped to a single project.`,
     branch_name: branchName,
     project_path: root,
-    worktree_path: path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`),
+    worktree_path: worktreePath,
     commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
     notes_content: '',
     pr_id: item.pr_id || item._pr || item.targetPr || item.sourcePr || item.pr || '',
@@ -3157,15 +3177,8 @@ function withWorkItemPrContext(item, pr) {
 function projectFromDispatchMeta(metaProject, config) {
   if (!metaProject) return null;
   const projects = getProjects(config);
-  if (metaProject.name) {
-    const byName = projects.find(p => p.name === metaProject.name);
-    if (byName) return byName;
-  }
-  if (metaProject.localPath) {
-    const refPath = path.resolve(metaProject.localPath);
-    const byPath = projects.find(p => p.localPath && path.resolve(p.localPath) === refPath);
-    if (byPath) return byPath;
-  }
+  const resolved = shared.resolveProjectSource(metaProject, projects, { allowCentral: false });
+  if (resolved.project) return resolved.project;
   return metaProject;
 }
 
@@ -3707,7 +3720,6 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
-  const projectsByName = new Map(dispatchProjects.map(p => [String(p.name || '').toLowerCase(), p]));
   const newWork = [];
   // Collect mutations to apply atomically inside lock callback (avoids TOCTOU)
   const mutations = new Map(); // item.id → { field: value, ... }
@@ -3750,9 +3762,9 @@ function discoverCentralWorkItems(config) {
 
     const workType = routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT);
     const isFanOut = item.scope === 'fan-out';
-    const explicitItemProject = typeof item.project === 'string' ? item.project : item.project?.name;
-    if (explicitItemProject && !projectsByName.get(String(explicitItemProject).toLowerCase())) {
-      const error = shared.formatUnknownProjectError(explicitItemProject, dispatchProjects);
+    const itemProjectResolution = shared.resolveConfiguredProject(item.project, projects);
+    if (itemProjectResolution.error) {
+      const error = itemProjectResolution.error;
       mutations.set(item.id, { status: WI_STATUS.FAILED, failReason: error, failedAt: ts() });
       log('warn', `central work item ${item.id}: ${error}`);
       continue;
@@ -3856,10 +3868,11 @@ function discoverCentralWorkItems(config) {
           planReadError = e;
         }
       }
-      const requestedProjectName = declaredPlanProject || (typeof item.project === 'string' ? item.project : item.project?.name);
-      const requestedProject = requestedProjectName ? projectsByName.get(String(requestedProjectName).toLowerCase()) : null;
-      if (requestedProjectName && !requestedProject) {
-        const error = shared.formatUnknownProjectError(requestedProjectName, dispatchProjects);
+      const requestedProjectResolution = declaredPlanProject
+        ? shared.resolveConfiguredProject(declaredPlanProject, projects)
+        : itemProjectResolution;
+      if (requestedProjectResolution.error) {
+        const error = requestedProjectResolution.error;
         mutations.set(item.id, {
           status: WI_STATUS.FAILED,
           failReason: error,
@@ -3869,7 +3882,7 @@ function discoverCentralWorkItems(config) {
         log('warn', `central work item ${item.id}: ${error}`);
         continue;
       }
-      const targetProject = requestedProject || (dispatchProjects.length === 1 ? dispatchProjects[0] : null);
+      const targetProject = requestedProjectResolution.project || (projects.length === 1 ? projects[0] : null);
       if (declaredPlanProject) {
         const projectMutation = { project: targetProject.name, _declaredPlanProject: declaredPlanProject };
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, projectMutation));
@@ -4920,6 +4933,7 @@ module.exports = {
 
   // Playbooks
   renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS, buildWorkItemDispatchVars,
+  renderProjectWorkItemPromptForAgent, // exported for testing
 
   // Timeout / Steering / Idle (re-exported from engine/timeout.js)
   checkTimeouts, checkSteering, checkIdleThreshold,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1810",
+  "version": "0.1.1812",
   "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/prompts/doc-chat-system.md

@@ -18,6 +18,18 @@ Before answering, classify the human's chat message:
 
 Do not emit `===ACTIONS===` or fenced `action` JSON for normal small document questions, summaries, rewrites, extraction, or localized edits. If a small task becomes medium/large after inspection, stop and dispatch a work item rather than pushing through in doc-chat.
 
+## Explicit Dispatch/Delegation Hard Stop
+
+Explicit dispatch/delegation intent hard stop: when the human's chat message asks to `dispatch`, `delegate`, `assign`, `have Minions...`, `open work items for...`, `queue fixes for...`, or otherwise asks another agent/minion/work item to do the work, you MUST emit `===ACTIONS===` with dispatch JSON when the required fields are available, and you MUST NOT use `Write`, `Edit`, or `Bash` against any file. If a required dispatch field is genuinely unknown, ask for that missing field in plain text; do not edit files or run Bash while waiting for clarification.
+
+This rule takes precedence over all document-editing paths below. Do not "helpfully" start implementing, fixing, or testing inline after acknowledging a dispatch/delegation request. The document may mention source files, contain findings, or list exact edits to make; those references are inputs for the dispatched work item's description, not permission to edit those files in doc-chat.
+
+Negative example A: if a findings or audit document is open and the human says "dispatch fixes for every issue", the correct response is one or more dispatch actions. Do not use `Edit`, `Write`, or `Bash` on source files referenced by the document, such as `engine.js`, `engine/pipeline.js`, or `test/unit.test.js`, even if the findings make the fix look obvious.
+
+Negative example B: if the human says "go fix these items", "implement this list", "have minions tackle these", or similar delegation phrasing, the correct response is dispatch action JSON. Do not edit the referenced implementation files directly from doc-chat.
+
+ANY `Edit` or `Write` call targeting a path other than the document-context `filePath` is forbidden, regardless of how compelling, urgent, or specific the human request sounds. If the requested work spans any file other than the current document filePath, dispatch it instead of editing it.
+
 ## Minions Orchestration Requests
 
 For explicit dispatch/delegation requests or medium/larger work without a direct-handling override, emit the same Command Center work-item action shape:
@@ -48,6 +60,6 @@ For wholesale rewrites, format conversions, or changes touching most of the file
 
 ### Rules for both paths
 
-- Never edit any file other than the one named in the document context.
+- Never edit any file other than the one named in the document context. `Edit`/`Write` against any other path is forbidden; if the work needs other files, dispatch it.
 - If the user is asking a question rather than requesting an edit, do not edit. Answer in plain text.
 - If a JSON file's edit would invalidate it, prefer the whole-file rewrite path so the server can validate the result before persisting.