@yemi33/minions 0.1.1807 → 0.1.1808

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1808 (2026-05-08)
+
+### Fixes
+-  Plan-to-PRD conversion can override explicit plan project with contextual project (#2235)
+
 ## 0.1.1807 (2026-05-08)
 
 ### Other

package/dashboard.js

@@ -5506,12 +5506,14 @@ const server = http.createServer(async (req, res) => {
       shared.sanitizePath(body.file, PLANS_DIR);
       const planPath = path.join(MINIONS_DIR, 'plans', body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
+      const planContent = fs.readFileSync(planPath, 'utf8');
+      const declaredProject = shared.extractPlanDeclaredProject(planContent);
 
       const queued = shared.queuePlanToPrd({
         planFile: body.file,
         title: 'Convert plan to PRD: ' + body.file.replace('.md', ''),
         description: 'Plan file: plans/' + body.file,
-        project: body.project || '', createdBy: 'dashboard:execute',
+        project: declaredProject || body.project || '', createdBy: 'dashboard:execute',
       });
       if (!queued) return jsonReply(res, 200, { ok: true, alreadyQueued: true });
       invalidateStatusCache();

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-08T19:31:14.792Z"
+  "cachedAt": "2026-05-08T20:57:25.233Z"
 }

package/engine/playbook.js

@@ -332,14 +332,29 @@ function validatePlaybookVars(playbookName, vars) {
  * @param {string} playbookType — playbook type name (e.g. 'implement', 'review')
  * @returns {string} absolute path to the playbook file
  */
+function isSafeProjectPlaybookName(projectName) {
+  const name = String(projectName || '').trim();
+  return !!name &&
+    !name.includes('\0') &&
+    !name.includes('..') &&
+    !/[\\/]/.test(name) &&
+    !path.isAbsolute(name) &&
+    !/^[a-zA-Z]:/.test(name);
+}
+
 function resolvePlaybookPath(projectName, playbookType) {
   if (projectName) {
-    const localPath = path.join(MINIONS_DIR, 'projects', projectName, 'playbooks', `${playbookType}.md`);
-    try {
-      fs.accessSync(localPath, fs.constants.R_OK);
-      log('info', `Using project-local playbook: projects/${projectName}/playbooks/${playbookType}.md`);
-      return localPath;
-    } catch { /* no local override — fall through to global */ }
+    const projectDirName = String(projectName).trim();
+    if (isSafeProjectPlaybookName(projectDirName)) {
+      const localPath = path.join(MINIONS_DIR, 'projects', projectDirName, 'playbooks', `${playbookType}.md`);
+      try {
+        fs.accessSync(localPath, fs.constants.R_OK);
+        log('info', `Using project-local playbook: projects/${projectDirName}/playbooks/${playbookType}.md`);
+        return localPath;
+      } catch { /* no local override — fall through to global */ }
+    } else {
+      log('warn', `Skipping project-local playbook lookup for unsafe project name: ${projectDirName}`);
+    }
   }
   return path.join(PLAYBOOKS_DIR, `${playbookType}.md`);
 }

package/engine/shared.js

@@ -1579,6 +1579,24 @@ function queuePlanToPrd({ planFile, prdFile, title, description, project, create
   }, { defaultValue: [] });
   return queued;
 }
+
+function extractPlanDeclaredProject(planContent) {
+  if (typeof planContent !== 'string' || !planContent.trim()) return '';
+  const lines = planContent.split(/\r?\n/).slice(0, 80);
+  for (const rawLine of lines) {
+    const line = rawLine
+      .replace(/^\s*[-*]\s+/, '')
+      .replace(/\*\*/g, '')
+      .trim();
+    const match = line.match(/^Project\s*:\s*(.+)$/i);
+    if (!match) continue;
+    let value = match[1].trim();
+    value = value.replace(/\s+#.*$/, '').trim();
+    value = value.replace(/^["'`]+|["'`]+$/g, '').trim();
+    return value;
+  }
+  return '';
+}
 const DISPATCH_RESULT = { SUCCESS: 'success', ERROR: 'error', TIMEOUT: 'timeout' };
 const PIPELINE_STATUS = {
   PENDING: 'pending', RUNNING: 'running', COMPLETED: 'completed',
@@ -3257,7 +3275,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
@@ -3302,6 +3320,7 @@ module.exports = {
   getAdoOrgBase,
   sanitizePath,
   sanitizeBranch,
+  safeSlugComponent,
   buildWorktreeDirName, // exported for testing
   isPathInside,
   isPathInsideOrEqual,

package/engine.js

@@ -1978,6 +1978,20 @@ function buildWiDescription(item, planFile) {
   return `${item.description || ''}\n\n**Plan:** ${planFile}\n**Plan Item:** ${item.id}\n**Complexity:** ${complexity}${criteria ? '\n\n**Acceptance Criteria:**\n' + criteria : ''}`;
 }
 
+function safePrdProjectSlug(projectName) {
+  const slug = shared.safeSlugComponent(projectName || 'project', 80)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'project';
+}
+
+function safePrdFilenameForProject(projectName, suffix) {
+  const fileName = `${safePrdProjectSlug(projectName)}-${suffix}.json`;
+  shared.sanitizePath(fileName, PRD_DIR);
+  return fileName;
+}
+
 function materializePlansAsWorkItems(config) {
   if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
   const writePrdLocked = (fileName, data) => {
@@ -1990,6 +2004,100 @@ function materializePlansAsWorkItems(config) {
       return mutator(current) || current;
     }, { defaultValue: fallback || {}, ...options });
   };
+  const declaredProjectPrdFilename = (fileName, projectName) => {
+    const match = String(fileName || '').match(/-(\d{4}-\d{2}-\d{2}(?:-\d+)?)\.json$/);
+    if (!match) return null;
+    return safePrdFilenameForProject(projectName, match[1]);
+  };
+  const migratePrdFilenameReferences = (oldFileName, newFileName) => {
+    if (!oldFileName || !newFileName || oldFileName === newFileName) return 0;
+    let migrated = 0;
+    const wiPaths = new Set([path.join(MINIONS_DIR, 'work-items.json')]);
+    for (const project of getProjects(config)) wiPaths.add(projectWorkItemsPath(project));
+    for (const wiPath of wiPaths) {
+      if (!fs.existsSync(wiPath)) continue;
+      mutateWorkItems(wiPath, (items) => {
+        for (const wi of items) {
+          if (!wi || typeof wi !== 'object') continue;
+          if (wi.sourcePlan === oldFileName) {
+            wi.sourcePlan = newFileName;
+            migrated++;
+          }
+          if (wi._artifacts?.sourcePlan === oldFileName) {
+            wi._artifacts.sourcePlan = newFileName;
+            migrated++;
+          }
+        }
+        return items;
+      });
+    }
+    if (fs.existsSync(DISPATCH_PATH)) {
+      mutateDispatch((dispatch) => {
+        for (const queue of ['pending', 'active', 'completed']) {
+          for (const entry of dispatch[queue] || []) {
+            const metaItem = entry?.meta?.item;
+            if (!metaItem || typeof metaItem !== 'object') continue;
+            if (metaItem.sourcePlan === oldFileName) {
+              metaItem.sourcePlan = newFileName;
+              migrated++;
+            }
+            if (metaItem._prdFilename === oldFileName) {
+              metaItem._prdFilename = newFileName;
+              migrated++;
+            }
+          }
+        }
+        return dispatch;
+      });
+    }
+    return migrated;
+  };
+  const enforceDeclaredPlanProject = (fileName, currentPlan) => {
+    if (!currentPlan?.source_plan) return { fileName, plan: currentPlan };
+    let declaredProject = '';
+    try {
+      declaredProject = shared.extractPlanDeclaredProject(safeRead(path.join(PLANS_DIR, currentPlan.source_plan)) || '');
+    } catch (e) {
+      log('warn', `Plan project enforcement: could not read source plan ${currentPlan.source_plan}: ${e.message}`);
+    }
+    if (!declaredProject) return { fileName, plan: currentPlan };
+
+    let changed = false;
+    const normalizedPlan = mutatePrdLocked(fileName, currentPlan, (planData) => {
+      if (planData.project !== declaredProject) {
+        planData.project = declaredProject;
+        changed = true;
+      }
+      if (Array.isArray(planData.missing_features)) {
+        for (const feature of planData.missing_features) {
+          if (feature && feature.project !== declaredProject) {
+            feature.project = declaredProject;
+            changed = true;
+          }
+        }
+      }
+      return planData;
+    }, { skipWriteIfUnchanged: true });
+
+    let nextFileName = fileName;
+    const desiredFileName = declaredProjectPrdFilename(fileName, declaredProject);
+    if (desiredFileName && desiredFileName.toLowerCase() !== String(fileName).toLowerCase()) {
+      const fromPath = path.join(PRD_DIR, fileName);
+      const desiredPath = shared.sanitizePath(desiredFileName, PRD_DIR);
+      const toPath = shared.uniquePath(desiredPath);
+      try {
+        fs.renameSync(fromPath, toPath);
+        nextFileName = path.basename(toPath);
+        const migrated = migratePrdFilenameReferences(fileName, nextFileName);
+        if (migrated > 0) log('info', `Plan project enforcement: migrated ${migrated} PRD reference(s) from ${fileName} to ${nextFileName}`);
+        changed = true;
+      } catch (e) {
+        log('warn', `Plan project enforcement: could not rename ${fileName} to ${path.basename(toPath)}: ${e.message}`);
+      }
+    }
+    if (changed) log('info', `Plan project enforcement: preserved declared project "${declaredProject}" for ${nextFileName}`);
+    return { fileName: nextFileName, plan: normalizedPlan };
+  };
 
   // Enforce: PRDs must be .json — auto-rename .md files that contain valid PRD JSON
   // Check both prd/ and plans/ (agents may still write JSON to plans/)
@@ -2036,12 +2144,13 @@ function materializePlansAsWorkItems(config) {
   // Regex for detecting sequential PRD item IDs (P-001, P-002) — hoisted outside loop
   const SEQUENTIAL_ID_RE = /^P-?\d+$/;
 
-  for (const file of planFiles) {
+  for (let file of planFiles) {
     // safeJsonNoRestore — if a PRD was archived between readdir and this
     // read, do not auto-resurrect it from a stale .backup sidecar
     // (W-mouptdh1000h9f39).
     let plan = safeJsonNoRestore(path.join(PRD_DIR, file));
     if (!plan?.missing_features) continue;
+    ({ fileName: file, plan } = enforceDeclaredPlanProject(file, plan));
 
     // ID collision prevention: remap sequential IDs (P-001, P-002) to globally unique P-<uid> IDs.
     // Agents are instructed to use P-<uuid> format but sometimes generate sequential IDs,
@@ -3576,7 +3685,7 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
-  const projectsByName = new Map(dispatchProjects.map(p => [p.name, p]));
+  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, ... }
@@ -3706,9 +3815,32 @@ function discoverCentralWorkItems(config) {
 
       const agentName = config.agents[agentId]?.name || agentId;
       const agentRole = config.agents[agentId]?.role || 'Agent';
+      let planFileContent = null;
+      let planReadError = null;
+      let declaredPlanProject = '';
+      if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile) {
+        const planPath = path.join(PLANS_DIR, item.planFile);
+        try {
+          planFileContent = fs.readFileSync(planPath, 'utf8');
+          declaredPlanProject = shared.extractPlanDeclaredProject(planFileContent);
+        } catch (e) {
+          planReadError = e;
+        }
+      }
       const firstProject = dispatchProjects[0];
-      const requestedProjectName = typeof item.project === 'string' ? item.project : item.project?.name;
-      const targetProject = (requestedProjectName && projectsByName.get(requestedProjectName)) || firstProject;
+      const requestedProjectName = declaredPlanProject || (typeof item.project === 'string' ? item.project : item.project?.name);
+      const requestedProject = requestedProjectName ? projectsByName.get(String(requestedProjectName).toLowerCase()) : null;
+      const targetProject = requestedProject || (declaredPlanProject
+        ? { name: declaredPlanProject, localPath: '', repoName: declaredPlanProject, mainBranch: firstProject?.mainBranch || 'main' }
+        : firstProject);
+      if (declaredPlanProject) {
+        const projectMutation = { project: targetProject.name, _declaredPlanProject: declaredPlanProject };
+        if (!requestedProject) projectMutation._declaredPlanProjectMissing = true;
+        mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, projectMutation));
+        if (!requestedProject) {
+          log('warn', `plan-to-prd: plan ${item.planFile} declares project "${declaredPlanProject}" but no configured project matches; preserving the declared project name with no project_path`);
+        }
+      }
 
       // Branch mutex: skip if target branch is locked by an active dispatch
       const centralBranch = item.branch || item.featureBranch || `work/${item.id}`;
@@ -3776,16 +3908,16 @@ function discoverCentralWorkItems(config) {
       if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile) {
         if (!fs.existsSync(PLANS_DIR)) fs.mkdirSync(PLANS_DIR, { recursive: true });
         if (!fs.existsSync(PRD_DIR)) fs.mkdirSync(PRD_DIR, { recursive: true });
-        const planPath = path.join(PLANS_DIR, item.planFile);
-        try {
-          vars.plan_content = fs.readFileSync(planPath, 'utf8');
-        } catch (e) {
-          log('warn', `plan-to-prd: could not read plan file ${item.planFile} for ${item.id}: ${e.message}`);
+        if (planFileContent !== null) {
+          vars.plan_content = planFileContent;
+        } else {
+          if (planReadError) log('warn', `plan-to-prd: could not read plan file ${item.planFile} for ${item.id}: ${planReadError.message}`);
           vars.plan_content = item.description || '';
         }
         vars.plan_summary = (item.title || item.planFile).substring(0, 80);
         vars.plan_file = item.planFile || '';
         vars.project_name_lower = (targetProject?.name || 'project').toLowerCase();
+        vars.project_filename_slug = safePrdProjectSlug(targetProject?.name || 'project');
         // Default empty string so the {{existing_prd_json}} token always resolves —
         // playbook treats empty as "no existing PRD, fresh run". Without this default
         // the renderPlaybook pass logs an "unresolved template variables" warning
@@ -3805,8 +3937,9 @@ function discoverCentralWorkItems(config) {
         }
         if (!prdFilename) {
           // Generate unique PRD filename — check prd/ and prd/archive/ for collisions
-          const prdBase = vars.project_name_lower + '-' + dateStamp();
+          const prdBase = vars.project_filename_slug + '-' + dateStamp();
           prdFilename = prdBase + '.json';
+          shared.sanitizePath(prdFilename, PRD_DIR);
           const prdExisting = new Set([
             ...prdFiles,
             ...safeReadDir(path.join(PRD_DIR, 'archive')).filter(f => f.endsWith('.json')),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1807",
+  "version": "0.1.1808",
   "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/plan-to-prd.md

@@ -14,6 +14,7 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 ## Instructions
 
 1. **Read the plan carefully** — understand the goals, scope, and requirements
+   - If the plan declares `Project: <name>` (including `**Project:** <name>`), the engine has resolved `{{project_name}}` from that declaration. Preserve `{{project_name}}` for the top-level `project`, default item `project`, filename, and implementation framing; do not let contextual mentions of another product or repository override it.
 2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
 3. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — status is determined only by existing PRD items (step 2), not codebase state
 4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work, with enough detail for another agent to implement it directly
@@ -47,7 +48,7 @@ This file is NOT checked into the repo. The engine reads it on every tick and di
       "id": "P-<uuid>",
       "name": "Short feature name",
       "description": "What needs to be built and why",
-      "project": "ProjectName",
+      "project": "{{project_name}}",
       "status": "missing",
       "estimated_complexity": "small|medium|large",
       "priority": "high|medium|low",
@@ -86,7 +87,7 @@ Rules for items:
 - IDs must be `P-<uuid>` format (e.g. `P-a3f9b2c1`) — globally unique, never sequential
 - **`status` is `"missing"` for new items** — do not set `done`, `complete`, `implemented`, or any other value based on codebase observations. The only exception is when reusing an existing PRD (see below) — items already `"done"` in the existing PRD carry forward as `"done"`. Pre-setting any other status on new items causes them to be silently skipped by the engine.
 - **Do NOT include a "verify" or "test" or "integration test" item** — the engine automatically creates a verify task when all PRD items are done. Adding one manually creates a duplicate that blocks plan completion.
-- **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
+- **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). If the plan declares a single project, every item must use `{{project_name}}`; contextual mentions of another repo/product must not override it. Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
 - `depends_on` lists IDs of items that must be done first
 - Keep descriptions actionable — name the files, functions, patterns, or integration points the implementing agent should touch whenever the plan makes them clear
 - Include `acceptance_criteria` so reviewers know when it's done