@yemi33/squad 0.1.5 → 0.1.7

package/engine.js

@@ -600,16 +600,29 @@ function spawnAgent(dispatchItem, config) {
     worktreePath = path.resolve(rootDir, engineConfig.worktreeRoot || '../worktrees', branchName);
     try {
       if (!fs.existsSync(worktreePath)) {
-        log('info', `Creating worktree: ${worktreePath} on branch ${branchName}`);
-        execSync(`git worktree add "${worktreePath}" -b "${branchName}" ${sanitizeBranch(project.mainBranch || 'main')}`, {
-          cwd: rootDir, stdio: 'pipe'
-        });
+        const isSharedBranch = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
+        if (isSharedBranch) {
+          // Shared branch: fetch and checkout existing branch (no -b)
+          log('info', `Creating worktree for shared branch: ${worktreePath} on ${branchName}`);
+          try { execSync(`git fetch origin "${branchName}"`, { cwd: rootDir, stdio: 'pipe' }); } catch {}
+          execSync(`git worktree add "${worktreePath}" "${branchName}"`, { cwd: rootDir, stdio: 'pipe' });
+        } else {
+          // Parallel: create new branch
+          log('info', `Creating worktree: ${worktreePath} on branch ${branchName}`);
+          execSync(`git worktree add "${worktreePath}" -b "${branchName}" ${sanitizeBranch(project.mainBranch || 'main')}`, {
+            cwd: rootDir, stdio: 'pipe'
+          });
+        }
+      } else if (meta?.branchStrategy === 'shared-branch') {
+        // Worktree exists — pull latest from prior plan item
+        log('info', `Pulling latest on shared branch ${branchName}`);
+        try { execSync(`git pull origin "${branchName}"`, { cwd: worktreePath, stdio: 'pipe' }); } catch {}
       }
       cwd = worktreePath;
     } catch (err) {
       log('error', `Failed to create worktree for ${branchName}: ${err.message}`);
       // Fall back to main directory for non-writing tasks
-      if (type === 'review' || type === 'analyze' || type === 'plan-to-prd') {
+      if (type === 'review' || type === 'analyze' || type === 'plan-to-prd' || type === 'plan') {
         cwd = rootDir;
       } else {
         completeDispatch(id, 'error', 'Worktree creation failed');
@@ -730,6 +743,16 @@ function spawnAgent(dispatchItem, config) {
       updateWorkItemStatus(meta, 'done', '');
     }
 
+    // Post-completion: chain plan → plan-to-prd if this was a plan task
+    if (code === 0 && type === 'plan' && meta?.item?.chain === 'plan-to-prd') {
+      chainPlanToPrd(dispatchItem, meta, config);
+    }
+
+    // Post-completion: check shared-branch plan completion
+    if (code === 0 && meta?.item?.branchStrategy === 'shared-branch') {
+      checkPlanCompletion(meta, config);
+    }
+
     // Post-completion: scan output for PRs and sync to pull-requests.json
     if (code === 0) {
       syncPrsFromOutput(stdout, agentId, meta, config);
@@ -872,6 +895,223 @@ function completeDispatch(id, result = 'success', reason = '') {
   }
 }
 
+// ─── Dependency Gate ─────────────────────────────────────────────────────────
+function areDependenciesMet(item, config) {
+  const deps = item.depends_on;
+  if (!deps || deps.length === 0) return true;
+  const sourcePlan = item.sourcePlan;
+  if (!sourcePlan) return true;
+  const projectName = item.project;
+  const projects = getProjects(config);
+  const project = projectName
+    ? projects.find(p => p.name?.toLowerCase() === projectName?.toLowerCase())
+    : projects[0];
+  if (!project) return true;
+  const wiPath = projectWorkItemsPath(project);
+  const workItems = safeJson(wiPath) || [];
+  for (const depId of deps) {
+    const depItem = workItems.find(w => w.sourcePlan === sourcePlan && w.planItemId === depId);
+    if (!depItem || depItem.status !== 'done') return false;
+  }
+  return true;
+}
+
+function detectDependencyCycles(items) {
+  const graph = new Map();
+  for (const item of items) graph.set(item.id, item.depends_on || []);
+  const visited = new Set(), inStack = new Set(), cycleIds = new Set();
+  function dfs(id) {
+    if (inStack.has(id)) { cycleIds.add(id); return true; }
+    if (visited.has(id)) return false;
+    visited.add(id); inStack.add(id);
+    for (const dep of (graph.get(id) || [])) { if (dfs(dep)) cycleIds.add(id); }
+    inStack.delete(id); return false;
+  }
+  for (const id of graph.keys()) dfs(id);
+  return [...cycleIds];
+}
+
+// ─── Plan Completion Detection ───────────────────────────────────────────────
+function checkPlanCompletion(meta, config) {
+  const planFile = meta.item?.sourcePlan;
+  if (!planFile) return;
+  const plan = safeJson(path.join(PLANS_DIR, planFile));
+  if (!plan?.missing_features || plan.branch_strategy !== 'shared-branch') return;
+  if (plan.status === 'completed') return;
+  const projectName = plan.project;
+  const projects = getProjects(config);
+  const project = projectName
+    ? projects.find(p => p.name?.toLowerCase() === projectName?.toLowerCase()) : projects[0];
+  if (!project) return;
+  const wiPath = projectWorkItemsPath(project);
+  const workItems = safeJson(wiPath) || [];
+  const planItems = workItems.filter(w => w.sourcePlan === planFile && w.planItemId !== 'PR');
+  if (planItems.length === 0) return;
+  if (!planItems.every(w => w.status === 'done')) return;
+  log('info', `All ${planItems.length} items in plan ${planFile} completed — creating PR work item`);
+  const maxNum = workItems.reduce((max, i) => {
+    const m = (i.id || '').match(/(\d+)$/);
+    return m ? Math.max(max, parseInt(m[1])) : max;
+  }, 0);
+  const id = 'PL-W' + String(maxNum + 1).padStart(3, '0');
+  const featureBranch = plan.feature_branch;
+  const mainBranch = project.mainBranch || 'main';
+  const itemSummary = planItems.map(w => '- ' + w.planItemId + ': ' + w.title.replace('Implement: ', '')).join('\n');
+  workItems.push({
+    id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
+    type: 'implement', priority: 'high',
+    description: `All plan items from \`${planFile}\` are complete on branch \`${featureBranch}\`.
+Create a pull request and clean up the worktree.
+
+**Branch:** \`${featureBranch}\`
+**Target:** \`${mainBranch}\`
+
+## Completed Items
+${itemSummary}
+
+## Instructions
+1. Rebase onto ${mainBranch} if needed (abort if conflicts — PR as-is is fine)
+2. Push: git push origin ${featureBranch} --force-with-lease
+3. Create the PR targeting ${mainBranch}
+4. Cleanup: git worktree remove ../worktrees/${featureBranch} --force`,
+    status: 'pending', created: ts(), createdBy: 'engine:plan-completion',
+    sourcePlan: planFile, planItemId: 'PR',
+    branch: featureBranch, branchStrategy: 'shared-branch', project: projectName,
+  });
+  safeWrite(wiPath, workItems);
+  plan.status = 'completed'; plan.completedAt = ts();
+  safeWrite(path.join(PLANS_DIR, planFile), plan);
+}
+
+// ─── Plan → PRD Chaining ─────────────────────────────────────────────────────
+// When a 'plan' type task completes, find the plan file it wrote and dispatch
+// a plan-to-prd task so Lambert converts it to structured PRD items.
+function chainPlanToPrd(dispatchItem, meta, config) {
+  const planDir = path.join(SQUAD_DIR, 'plans');
+  if (!fs.existsSync(planDir)) {
+    log('warn', `Plan chaining: no plans/ directory found after plan task ${dispatchItem.id}`);
+    return;
+  }
+
+  // Find the plan file — look for recently created .md files in plans/
+  const planFiles = fs.readdirSync(planDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => ({ name: f, mtime: fs.statSync(path.join(planDir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  // Use the most recently modified plan file (the one the plan agent just wrote)
+  const planFile = planFiles[0];
+  if (!planFile) {
+    log('warn', `Plan chaining: no .md plan files found in plans/ after task ${dispatchItem.id}`);
+    return;
+  }
+
+  const planPath = path.join(planDir, planFile.name);
+  let planContent;
+  try { planContent = fs.readFileSync(planPath, 'utf8'); } catch (e) {
+    log('error', `Plan chaining: failed to read plan file ${planFile.name}: ${e.message}`);
+    return;
+  }
+
+  // Resolve target project
+  const projectName = meta?.item?.project || meta?.project?.name;
+  const projects = getProjects(config);
+  const targetProject = projectName
+    ? projects.find(p => p.name === projectName) || projects[0]
+    : projects[0];
+
+  if (!targetProject) {
+    log('error', 'Plan chaining: no target project available');
+    return;
+  }
+
+  // Resolve agent for plan-to-prd (typically Lambert)
+  const agentId = resolveAgent('plan-to-prd', config);
+  if (!agentId) {
+    // No agent available now — create a pending work item so engine picks it up on next tick
+    log('info', `Plan chaining: no agent available now, queuing plan-to-prd for next tick`);
+    const wiPath = path.join(SQUAD_DIR, 'work-items.json');
+    let items = [];
+    try { items = JSON.parse(fs.readFileSync(wiPath, 'utf8')); } catch {}
+    const maxNum = items.reduce((max, i) => {
+      const m = (i.id || '').match(/(\d+)$/);
+      return m ? Math.max(max, parseInt(m[1])) : max;
+    }, 0);
+    items.push({
+      id: 'W' + String(maxNum + 1).padStart(3, '0'),
+      title: `Convert plan to PRD: ${meta?.item?.title || planFile.name}`,
+      type: 'plan-to-prd',
+      priority: meta?.item?.priority || 'high',
+      description: `Plan file: plans/${planFile.name}\nChained from plan task ${dispatchItem.id}`,
+      status: 'pending',
+      created: ts(),
+      createdBy: 'engine:chain',
+      project: targetProject.name,
+      planFile: planFile.name,
+    });
+    safeWrite(wiPath, items);
+    return;
+  }
+
+  // Build plan-to-prd vars and dispatch immediately
+  const vars = {
+    agent_id: agentId,
+    agent_name: config.agents[agentId]?.name || agentId,
+    agent_role: config.agents[agentId]?.role || '',
+    project_name: targetProject.name || 'Unknown',
+    project_path: targetProject.localPath || '',
+    main_branch: targetProject.mainBranch || 'main',
+    ado_org: targetProject.adoOrg || config.project?.adoOrg || 'Unknown',
+    ado_project: targetProject.adoProject || config.project?.adoProject || 'Unknown',
+    repo_name: targetProject.repoName || config.project?.repoName || 'Unknown',
+    team_root: SQUAD_DIR,
+    date: dateStamp(),
+    plan_content: planContent,
+    plan_summary: (meta?.item?.title || planFile.name).substring(0, 80),
+    project_name_lower: (targetProject.name || 'project').toLowerCase(),
+    branch_strategy_hint: meta?.item?.branchStrategy
+      ? `The user requested **${meta.item.branchStrategy}** strategy. Use this unless the analysis strongly suggests otherwise.`
+      : 'Choose the best strategy based on your analysis of item dependencies.',
+  };
+
+  if (!fs.existsSync(PLANS_DIR)) fs.mkdirSync(PLANS_DIR, { recursive: true });
+
+  const prompt = renderPlaybook('plan-to-prd', vars);
+  if (!prompt) {
+    log('error', 'Plan chaining: could not render plan-to-prd playbook');
+    return;
+  }
+
+  const id = addToDispatch({
+    type: 'plan-to-prd',
+    agent: agentId,
+    agentName: config.agents[agentId]?.name,
+    agentRole: config.agents[agentId]?.role,
+    task: `[${targetProject.name}] Convert plan to PRD: ${vars.plan_summary}`,
+    prompt,
+    meta: {
+      source: 'chain',
+      chainedFrom: dispatchItem.id,
+      project: { name: targetProject.name, localPath: targetProject.localPath },
+      planFile: planFile.name,
+      planSummary: vars.plan_summary,
+    }
+  });
+
+  log('info', `Plan chaining: dispatched plan-to-prd ${id} → ${config.agents[agentId]?.name} (chained from ${dispatchItem.id})`);
+
+  // Spawn immediately if engine is running
+  const control = getControl();
+  if (control.state === 'running') {
+    const dispatch = getDispatch();
+    const item = dispatch.pending.find(d => d.id === id);
+    if (item) {
+      spawnAgent(item, config);
+      log('info', `Plan chaining: agent spawned immediately for ${id}`);
+    }
+  }
+}
+
 function updateWorkItemStatus(meta, status, reason) {
   const itemId = meta.item?.id;
   if (!itemId) return;
@@ -1334,6 +1574,114 @@ async function pollPrStatus(config) {
   }
 }
 
+// ─── Poll Human Comments on PRs ──────────────────────────────────────────────
+
+async function pollPrHumanComments(config) {
+  const token = getAdoToken();
+  if (!token) return;
+
+  const projects = getProjects(config);
+  let totalUpdated = 0;
+
+  for (const project of projects) {
+    if (!project.adoOrg || !project.adoProject || !project.repositoryId) continue;
+
+    const prs = getPrs(project);
+    const activePrs = prs.filter(pr => pr.status === 'active');
+    if (activePrs.length === 0) continue;
+
+    let projectUpdated = 0;
+
+    for (const pr of activePrs) {
+      const prNum = (pr.id || '').replace('PR-', '');
+      if (!prNum) continue;
+
+      try {
+        let orgBase;
+        if (project.prUrlBase) {
+          const m = project.prUrlBase.match(/^(https?:\/\/[^/]+(?:\/DefaultCollection)?)/);
+          if (m) orgBase = m[1];
+        }
+        if (!orgBase) {
+          orgBase = project.adoOrg.includes('.')
+            ? `https://${project.adoOrg}`
+            : `https://dev.azure.com/${project.adoOrg}`;
+        }
+
+        const threadsUrl = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}/threads?api-version=7.1`;
+        const threadsData = await adoFetch(threadsUrl, token);
+        const threads = threadsData.value || [];
+
+        // First pass: count all unique human commenters across the entire PR
+        const allHumanAuthors = new Set();
+        for (const thread of threads) {
+          for (const comment of (thread.comments || [])) {
+            if (!comment.content || comment.commentType === 'system') continue;
+            if (/\bSquad\s*\(/i.test(comment.content)) continue;
+            allHumanAuthors.add(comment.author?.uniqueName || comment.author?.displayName || '');
+          }
+        }
+        const soloReviewer = allHumanAuthors.size <= 1;
+
+        // Second pass: collect new human comments after cutoff
+        const cutoff = pr.humanFeedback?.lastProcessedCommentDate || pr.created || '1970-01-01';
+        const newHumanComments = [];
+
+        for (const thread of threads) {
+          for (const comment of (thread.comments || [])) {
+            if (!comment.content || comment.commentType === 'system') continue;
+            if (/\bSquad\s*\(/i.test(comment.content)) continue;
+            if (!(comment.publishedDate && comment.publishedDate > cutoff)) continue;
+
+            // Solo reviewer: all comments are actionable. Multiple humans: require @squad.
+            if (!soloReviewer && !/@squad\b/i.test(comment.content)) continue;
+
+            newHumanComments.push({
+              threadId: thread.id,
+              commentId: comment.id,
+              author: comment.author?.displayName || 'Human',
+              content: comment.content,
+              date: comment.publishedDate
+            });
+          }
+        }
+
+        if (newHumanComments.length === 0) continue;
+
+        // Sort by date, concatenate feedback
+        newHumanComments.sort((a, b) => a.date.localeCompare(b.date));
+        const feedbackContent = newHumanComments
+          .map(c => `**${c.author}** (${c.date}):\n${c.content.replace(/@squad\s*/gi, '').trim()}`)
+          .join('\n\n---\n\n');
+        const latestDate = newHumanComments[newHumanComments.length - 1].date;
+
+        pr.humanFeedback = {
+          lastProcessedCommentDate: latestDate,
+          pendingFix: true,
+          feedbackContent
+        };
+
+        log('info', `PR ${pr.id}: found ${newHumanComments.length} new human comment(s)${soloReviewer ? '' : ' (via @squad)'}`);
+        projectUpdated++;
+      } catch (e) {
+        log('warn', `Failed to poll comments for ${pr.id}: ${e.message}`);
+      }
+    }
+
+    if (projectUpdated > 0) {
+      const root = path.resolve(project.localPath);
+      const prSrc = project.workSources?.pullRequests || {};
+      const prPath = path.resolve(root, prSrc.path || '.squad/pull-requests.json');
+      safeWrite(prPath, prs);
+      totalUpdated += projectUpdated;
+    }
+  }
+
+  if (totalUpdated > 0) {
+    log('info', `PR comment poll: found human feedback on ${totalUpdated} PR(s)`);
+  }
+}
+
 // ─── Post-Merge / Post-Close Hooks ───────────────────────────────────────────
 
 async function handlePostMerge(pr, project, config, newStatus) {
@@ -1358,11 +1706,9 @@ async function handlePostMerge(pr, project, config, newStatus) {
   // Only run remaining hooks for merged PRs (not abandoned)
   if (newStatus !== 'merged') return;
 
-  // 2. Update PRD item status to 'implemented'
+  // 2. Update PRD item status to 'implemented' (squad-level PRD)
   if (pr.prdItems?.length > 0) {
-    const root = path.resolve(project.localPath);
-    const prdSrc = project.workSources?.prd || {};
-    const prdPath = path.resolve(root, prdSrc.path || 'docs/prd-gaps.json');
+    const prdPath = path.join(SQUAD_DIR, 'prd.json');
     const prd = safeJson(prdPath);
     if (prd?.missing_features) {
       let updated = 0;
@@ -2191,33 +2537,49 @@ function isAlreadyDispatched(key) {
 }
 
 /**
- * Scan PRD (docs/prd-gaps.json) for missing/planned items → queue implement tasks
+ * Scan squad-level PRD (~/.squad/prd.json) for missing/planned items → queue implement tasks.
+ * Items can span multiple projects via the `projects` array field.
  */
-function discoverFromPrd(config, project) {
-  const src = project?.workSources?.prd || config.workSources?.prd;
-  if (!src?.enabled) return [];
-
-  const root = project?.localPath ? path.resolve(project.localPath) : path.resolve(SQUAD_DIR, '..');
-  const prdPath = path.resolve(root, src.path);
+function discoverFromPrd(config) {
+  const prdPath = path.join(SQUAD_DIR, 'prd.json');
   const prd = safeJson(prdPath);
   if (!prd) return [];
 
-  const cooldownMs = (src.cooldownMinutes || 30) * 60 * 1000;
-  const statusFilter = src.itemFilter?.status || ['missing', 'planned'];
+  const cooldownMs = (config.workSources?.prd?.cooldownMinutes || 30) * 60 * 1000;
+  const statusFilter = config.workSources?.prd?.itemFilter?.status || ['missing', 'planned'];
   const items = (prd.missing_features || []).filter(f => statusFilter.includes(f.status));
   const newWork = [];
-  const skipped = { dispatched: 0, cooldown: 0, noAgent: 0 };
+  const skipped = { dispatched: 0, cooldown: 0, noAgent: 0, noProject: 0 };
+  const allProjects = config.projects || [];
 
   for (const item of items) {
-    const key = `prd-${project?.name || 'default'}-${item.id}`;
+    const key = `prd-squad-${item.id}`;
     if (isAlreadyDispatched(key)) { skipped.dispatched++; continue; }
     if (isOnCooldown(key, cooldownMs)) { skipped.cooldown++; continue; }
 
+    // Resolve target projects from item.projects array
+    const targetProjects = (item.projects || [])
+      .map(name => allProjects.find(p => p.name.toLowerCase() === name.toLowerCase()))
+      .filter(Boolean);
+    if (targetProjects.length === 0) { skipped.noProject++; continue; }
+
     const workType = item.estimated_complexity === 'large' ? 'implement:large' : 'implement';
     const agentId = resolveAgent(workType, config);
     if (!agentId) { skipped.noAgent++; continue; }
 
+    // Primary project = first in the list (used for worktree, branch, PR)
+    const primary = targetProjects[0];
+    const root = path.resolve(primary.localPath);
     const branchName = `feature/${item.id.toLowerCase()}-${item.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40)}`;
+
+    // Build related projects context for multi-project items
+    let relatedProjects = '';
+    if (targetProjects.length > 1) {
+      relatedProjects = targetProjects.map(p =>
+        `- **${p.name}** — ${path.resolve(p.localPath)} (${p.adoOrg}/${p.adoProject}/${p.repoName}, branch: ${p.mainBranch || 'main'})`
+      ).join('\n');
+    }
+
     const vars = {
       agent_id: agentId,
       agent_name: config.agents[agentId]?.name || agentId,
@@ -2229,15 +2591,16 @@ function discoverFromPrd(config, project) {
       item_description: item.description || '',
       branch_name: branchName,
       project_path: root,
-      main_branch: project?.mainBranch || 'main',
+      main_branch: primary.mainBranch || 'main',
       worktree_path: path.resolve(root, config.engine?.worktreeRoot || '../worktrees', branchName),
       commit_message: `feat(${item.id.toLowerCase()}): ${item.name}`,
       team_root: SQUAD_DIR,
-      repo_id: project?.repositoryId || config.project?.repositoryId || '',
-      project_name: project?.name || config.project?.name || 'Unknown Project',
-      ado_org: project?.adoOrg || config.project?.adoOrg || 'Unknown',
-      ado_project: project?.adoProject || config.project?.adoProject || 'Unknown',
-      repo_name: project?.repoName || config.project?.repoName || 'Unknown'
+      repo_id: primary.repositoryId || '',
+      project_name: targetProjects.map(p => p.name).join(', '),
+      ado_org: primary.adoOrg || 'Unknown',
+      ado_project: primary.adoProject || 'Unknown',
+      repo_name: primary.repoName || 'Unknown',
+      related_projects: relatedProjects,
     };
 
     const prompt = renderPlaybook('implement', vars);
@@ -2248,17 +2611,17 @@ function discoverFromPrd(config, project) {
       agent: agentId,
       agentName: config.agents[agentId]?.name,
       agentRole: config.agents[agentId]?.role,
-      task: `[${project?.name || 'project'}] Implement ${item.id}: ${item.name}`,
+      task: `[${vars.project_name}] Implement ${item.id}: ${item.name}`,
       prompt,
-      meta: { dispatchKey: key, source: 'prd', branch: branchName, item, project: { name: project?.name, localPath: project?.localPath } }
+      meta: { dispatchKey: key, source: 'prd', branch: branchName, item, project: { name: primary.name, localPath: primary.localPath } }
     });
 
     setCooldown(key);
   }
 
-  const skipTotal = skipped.dispatched + skipped.cooldown + skipped.noAgent;
+  const skipTotal = skipped.dispatched + skipped.cooldown + skipped.noAgent + skipped.noProject;
   if (skipTotal > 0) {
-    log('debug', `PRD discovery (${project?.name}): skipped ${skipTotal} items (${skipped.dispatched} dispatched, ${skipped.cooldown} cooldown, ${skipped.noAgent} no agent)`);
+    log('debug', `PRD discovery: skipped ${skipTotal} items (${skipped.dispatched} dispatched, ${skipped.cooldown} cooldown, ${skipped.noAgent} no agent, ${skipped.noProject} no project)`);
   }
 
   return newWork;
@@ -2316,7 +2679,12 @@ function materializePlansAsWorkItems(config) {
         created: ts(),
         createdBy: 'engine:plan-discovery',
         sourcePlan: file,
-        sourcePlanItem: item.id
+        sourcePlanItem: item.id,
+        planItemId: item.id,
+        depends_on: item.depends_on || [],
+        branchStrategy: plan.branch_strategy || 'parallel',
+        featureBranch: plan.feature_branch || null,
+        project: plan.project || null,
       });
       created++;
     }
@@ -2324,6 +2692,36 @@ function materializePlansAsWorkItems(config) {
     if (created > 0) {
       safeWrite(wiPath, existingItems);
       log('info', `Plan discovery: created ${created} work item(s) from ${file} → ${project.name}`);
+
+      // Pre-create shared feature branch if branch_strategy is shared-branch
+      if (plan.branch_strategy === 'shared-branch' && plan.feature_branch) {
+        try {
+          const root = path.resolve(project.localPath);
+          const mainBranch = project.mainBranch || 'main';
+          const branch = sanitizeBranch(plan.feature_branch);
+          // Create branch from main (idempotent — ignores if exists)
+          execSync(`git branch "${branch}" "${mainBranch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
+          execSync(`git push -u origin "${branch}" 2>/dev/null || true`, { cwd: root, stdio: 'pipe' });
+          log('info', `Shared branch pre-created: ${branch} for plan ${file}`);
+        } catch (err) {
+          log('warn', `Failed to pre-create shared branch for ${file}: ${err.message}`);
+        }
+      }
+
+      // Cycle detection for plan items
+      const planDerivedItems = plan.missing_features.filter(f => f.depends_on && f.depends_on.length > 0);
+      if (planDerivedItems.length > 0) {
+        const cycles = detectDependencyCycles(plan.missing_features);
+        if (cycles.length > 0) {
+          log('warn', `Dependency cycle detected in plan ${file}: ${cycles.join(', ')} — clearing deps for cycling items`);
+          for (const wi of existingItems) {
+            if (wi.sourcePlan === file && cycles.includes(wi.planItemId)) {
+              wi.depends_on = [];
+            }
+          }
+          safeWrite(wiPath, existingItems);
+        }
+      }
     }
   }
 }
@@ -2429,6 +2827,51 @@ function discoverFromPrs(config, project) {
       setCooldown(key);
     }
 
+    // PRs with pending human feedback (@squad comments) → route to author for fix
+    if (pr.humanFeedback?.pendingFix) {
+      const key = `human-fix-${project?.name || 'default'}-${pr.id}-${pr.humanFeedback.lastProcessedCommentDate}`;
+      if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
+
+      const agentId = resolveAgent('fix', config, pr.agent);
+      if (!agentId) continue;
+
+      const prNumber = (pr.id || '').replace(/^PR-/, '');
+      const vars = {
+        agent_id: agentId,
+        agent_name: config.agents[agentId]?.name || agentId,
+        agent_role: config.agents[agentId]?.role || 'Agent',
+        pr_id: pr.id,
+        pr_number: prNumber,
+        pr_title: pr.title || '',
+        pr_branch: pr.branch || '',
+        reviewer: 'Human Reviewer',
+        review_note: pr.humanFeedback.feedbackContent || 'See PR thread comments',
+        team_root: SQUAD_DIR,
+        repo_id: project?.repositoryId || config.project?.repositoryId || '',
+        project_name: project?.name || 'Unknown Project',
+        ado_org: project?.adoOrg || 'Unknown',
+        ado_project: project?.adoProject || 'Unknown',
+        repo_name: project?.repoName || 'Unknown'
+      };
+
+      const prompt = renderPlaybook('fix', vars);
+      if (!prompt) continue;
+
+      newWork.push({
+        type: 'fix',
+        agent: agentId,
+        agentName: config.agents[agentId]?.name,
+        agentRole: config.agents[agentId]?.role,
+        task: `[${project?.name || 'project'}] Fix PR ${pr.id} — human feedback`,
+        prompt,
+        meta: { dispatchKey: key, source: 'pr-human-feedback', pr, branch: pr.branch, project: { name: project?.name, localPath: project?.localPath } }
+      });
+
+      // Clear pendingFix so it doesn't re-dispatch next tick
+      pr.humanFeedback.pendingFix = false;
+      setCooldown(key);
+    }
+
     // PRs with build failures → route to any idle agent
     if (pr.status === 'active' && pr.buildStatus === 'failing') {
       const key = `build-fix-${project?.name || 'default'}-${pr.id}`;
@@ -2545,6 +2988,9 @@ function discoverFromWorkItems(config, project) {
   for (const item of items) {
     if (item.status !== 'queued' && item.status !== 'pending') continue;
 
+    // Dependency gate: skip items whose depends_on are not yet met
+    if (item.depends_on && item.depends_on.length > 0 && !areDependenciesMet(item, config)) continue;
+
     const key = `work-${project?.name || 'default'}-${item.id}`;
     if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) { skipped.gated++; continue; }
 
@@ -2555,7 +3001,8 @@ function discoverFromWorkItems(config, project) {
     const agentId = item.agent || resolveAgent(workType, config);
     if (!agentId) { skipped.noAgent++; continue; }
 
-    const branchName = item.branch || `work/${item.id}`;
+    const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;
+    const branchName = isShared ? item.featureBranch : (item.branch || `work/${item.id}`);
     const vars = {
       agent_id: agentId,
       agent_name: config.agents[agentId]?.name || agentId,
@@ -2581,9 +3028,22 @@ function discoverFromWorkItems(config, project) {
       date: dateStamp()
     };
 
-    // Use type-specific playbook if it exists (e.g., explore.md, review.md), fall back to work-item.md
-    const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd'];
-    const playbookName = typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
+    // Inject ask-specific variables for the ask playbook
+    if (workType === 'ask') {
+      vars.question = item.title + (item.description ? '\n\n' + item.description : '');
+      vars.task_id = item.id;
+      vars.notes_content = '';
+      try { vars.notes_content = fs.readFileSync(path.join(SQUAD_DIR, 'notes.md'), 'utf8'); } catch {}
+    }
+
+    // Select playbook: shared-branch items use implement-shared, others use type-specific or work-item
+    let playbookName;
+    if (item.branchStrategy === 'shared-branch' && (workType === 'implement' || workType === 'implement:large')) {
+      playbookName = 'implement-shared';
+    } else {
+      const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask'];
+      playbookName = typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
+    }
     const prompt = item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description;
     if (!prompt) {
       log('warn', `No playbook rendered for ${item.id} (type: ${workType}, playbook: ${playbookName}) — skipping`);
@@ -2602,7 +3062,7 @@ function discoverFromWorkItems(config, project) {
       agentRole: config.agents[agentId]?.role,
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
-      meta: { dispatchKey: key, source: 'work-item', branch: branchName, item, project: { name: project?.name, localPath: project?.localPath } }
+      meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(item.branchStrategy === 'shared-branch' && item.featureBranch), item, project: { name: project?.name, localPath: project?.localPath } }
     });
 
     setCooldown(key);
@@ -2859,7 +3319,15 @@ function discoverCentralWorkItems(config) {
           date: dateStamp()
         };
 
-        const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd'];
+        // Inject ask-specific variables for the ask playbook
+        if (workType === 'ask') {
+          vars.question = item.title + (item.description ? '\n\n' + item.description : '');
+          vars.task_id = item.id;
+          vars.notes_content = '';
+          try { vars.notes_content = fs.readFileSync(path.join(SQUAD_DIR, 'notes.md'), 'utf8'); } catch {}
+        }
+
+        const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask'];
         const playbookName = typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
         const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
         if (!prompt) continue;
@@ -2917,7 +3385,26 @@ function discoverCentralWorkItems(config) {
         date: dateStamp()
       };
 
-      const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd'];
+      // Inject plan-specific variables for the plan playbook
+      if (workType === 'plan') {
+        const planFileName = `plan-${item.id.toLowerCase()}-${dateStamp()}.md`;
+        vars.plan_content = item.title + (item.description ? '\n\n' + item.description : '');
+        vars.plan_title = item.title;
+        vars.plan_file = planFileName;
+        vars.task_description = item.title;
+        vars.notes_content = '';
+        try { vars.notes_content = fs.readFileSync(path.join(SQUAD_DIR, 'notes.md'), 'utf8'); } catch {}
+      }
+
+      // Inject ask-specific variables for the ask playbook
+      if (workType === 'ask') {
+        vars.question = item.title + (item.description ? '\n\n' + item.description : '');
+        vars.task_id = item.id;
+        vars.notes_content = '';
+        try { vars.notes_content = fs.readFileSync(path.join(SQUAD_DIR, 'notes.md'), 'utf8'); } catch {}
+      }
+
+      const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask'];
       const playbookName = typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
       const prompt = renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars);
       if (!prompt) continue;
@@ -2946,7 +3433,7 @@ function discoverCentralWorkItems(config) {
 
 /**
  * Run all work discovery sources and queue new items
- * Priority: fix (0) > review (1) > implement (2) > work-items (3) > central (4)
+ * Priority: fix (0) > ask (1) > review (1) > implement (2) > work-items (3) > central (4)
  */
 function discoverWork(config) {
   const projects = getProjects(config);
@@ -2966,9 +3453,6 @@ function discoverWork(config) {
     allReviews.push(...prWork.filter(w => w.type === 'review'));
     allWorkItems.push(...prWork.filter(w => w.type === 'test'));
 
-    // Source 2: PRD gaps → implements
-    allImplements.push(...discoverFromPrd(config, project));
-
     // Side-effect: specs → work items (picked up below)
     materializeSpecsAsWorkItems(config, project);
 
@@ -2976,6 +3460,9 @@ function discoverWork(config) {
     allWorkItems.push(...discoverFromWorkItems(config, project));
   }
 
+  // Source 2: Squad-level PRD → implements (multi-project, called once outside project loop)
+  allImplements.push(...discoverFromPrd(config));
+
   // Central work items (project-agnostic — agent decides where to work)
   const centralWork = discoverCentralWorkItems(config);
 
@@ -3038,6 +3525,11 @@ async function tickInner() {
     try { await pollPrStatus(config); } catch (e) { log('warn', `PR status poll error: ${e.message}`); }
   }
 
+  // 2.7. Poll PR threads for human @squad comments (every 12 ticks = ~6 minutes)
+  if (tickCount % 12 === 0) {
+    try { await pollPrHumanComments(config); } catch (e) { log('warn', `PR comment poll error: ${e.message}`); }
+  }
+
   // 3. Discover new work from sources
   discoverWork(config);
 
@@ -3057,7 +3549,7 @@ async function tickInner() {
   const slotsAvailable = maxConcurrent - activeCount;
 
   // Priority dispatch: fixes > reviews > plan-to-prd > implement > other
-  const typePriority = { fix: 0, review: 1, test: 2, 'plan-to-prd': 3, 'implement:large': 4, implement: 5 };
+  const typePriority = { fix: 0, ask: 1, review: 1, test: 2, plan: 3, 'plan-to-prd': 3, 'implement:large': 4, implement: 5 };
   const itemPriority = { high: 0, medium: 1, low: 2 };
   dispatch.pending.sort((a, b) => {
     const ta = typePriority[a.type] ?? 5, tb = typePriority[b.type] ?? 5;