@yemi33/minions 0.1.2218 → 0.1.2219

package/engine/ado.js

@@ -357,13 +357,19 @@ function applyAdoPrMetadata(pr, prData) {
   if (sourceBranch && (pr.branch !== sourceBranch || pr._branchResolutionError || pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH)) {
     // P-a7c4d2e8 (F3): validate ADO-derived branch ref before persistence.
     // On invalid ref, log + skip so the poller keeps running (defensive).
+    // Narrow try to only the throwing validateGitRef call (F20); the
+    // non-throwing assignment + field deletes run after on the success path.
+    let validatedBranch;
     try {
-      pr.branch = shared.validateGitRef(sourceBranch);
+      validatedBranch = shared.validateGitRef(sourceBranch);
+    } catch (refErr) {
+      log('warn', `ADO: invalid sourceRefName "${sourceBranch.slice(0, 64)}" for PR ${pr.id || '?'}: ${refErr.message}`);
+    }
+    if (validatedBranch !== undefined) {
+      pr.branch = validatedBranch;
       if (pr._branchResolutionError) delete pr._branchResolutionError;
       if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
       updated = true;
-    } catch (refErr) {
-      log('warn', `ADO: invalid sourceRefName "${sourceBranch.slice(0, 64)}" for PR ${pr.id || '?'}: ${refErr.message}`);
     }
   }
 

package/engine/cli.js

@@ -555,7 +555,11 @@ const commands = {
     // before tick #1 would flip its auto-managed verdict. Idempotent.
     try {
       const projectsRoot = path.join(shared.MINIONS_DIR, 'projects');
-      shared.migratePrGateFlags(projectsRoot);
+      // W-mqil3jtw — pass the configured agent roster so the migration
+      // cross-checks `agent` against real agent ids instead of a shape regex;
+      // a GitHub author login (e.g. `calebt_microsoft`) must not be mistaken
+      // for a managed persona and flip a context-only PR's observe toggle.
+      shared.migratePrGateFlags(projectsRoot, { config });
     } catch (err) { e.log('warn', `pr-gate-migration failed: ${err.message}`); }
 
     // One-time force-on of the CC worker pool. The pool has been the resolved

package/engine/github.js

@@ -1884,6 +1884,7 @@ module.exports = {
   dismissPriorViewerChangesRequestedReviews, // W-mp7b1g8q000fea45 — clear stale CHANGES_REQUESTED on verdict flip
   isGhThrottled,
   getGhThrottleState,
+  ghApi, // P-8c1b6e45 — used by engine/shared-branch-pr-reconcile.js to list open PRs on a feature branch
   // Exported for testing
   isGitHub,
   getRepoSlug,

package/engine/playbook.js

@@ -315,6 +315,12 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // creation. Optional because every other playbook ignores it and the
   // default state is the empty string (renders the non-shared branch).
   'shared_branch',
+  // P-7e1a9c34 — the canonical shared-branch name, exposed so any playbook can
+  // reference {{feature_branch}} without a second source of truth. Set by
+  // renderProjectWorkItemPromptForAgent to item.featureBranch for shared-branch
+  // work-item dispatches; '' for parallel/PR-targeted dispatches. Optional
+  // because most playbooks never reference it.
+  'feature_branch',
   // P-4d6e2af3 — comma-separated list of target projects for cross-repo
   // plans. Only set in engine.js's WORK_TYPE.PLAN branch when the WI carries
   // item._targetProjects (≥2 entries from dashboard.js#buildPlanWorkItem).

package/engine/queries.js

@@ -602,18 +602,6 @@ function getAgentStatus(agentId) {
     if (active._blockingToolCall) {
       result._blockingToolCall = active._blockingToolCall;
     }
-    // Detect in-flight tools: read only head+tail of live-output.log (max 2KB total)
-    try {
-      const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
-      const { head, tail } = readHeadTail(liveLogPath, 1024);
-      if (head) {
-        // Detect in-flight tool calls (task_started with no task_notification)
-        const inFlight = detectInFlightTool(tail);
-        if (inFlight && inFlight.description) {
-          result._runningToolDescription = inFlight.description;
-        }
-      }
-    } catch { /* optional — don't block status */ }
     return result;
   }
 
@@ -713,7 +701,12 @@ function getAgents(config) {
     const s = getAgentStatus(a.id); // derives from dispatch.json
 
     let lastAction = 'Waiting for assignment';
-    if (s.status === 'working') lastAction = s._runningToolDescription ? `Running: ${s._runningToolDescription}` : `Working: ${s.task}`;
+    // Show the dispatch task as a stable label for the whole run — don't swap
+    // in the transient per-tool-call `_runningToolDescription`, which reads like
+    // a task change to operators (e.g. an agent's own "Wait until temp dirs
+    // mostly cleared" bash step looked like a new task). Long-silent/blocking
+    // tool calls are still surfaced separately via `_blockingToolCall`.
+    if (s.status === 'working') lastAction = `Working: ${s.task}`;
     else if (DONE_STATUSES.has(s.status)) lastAction = `Done: ${s.task}`;
     else if (s.status === 'error') lastAction = `Error: ${s.task}`;
     else if (steeringInboxFiles.length > 0) {

package/engine/shared-branch-pr-reconcile.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Shared-branch PR reconciler (P-8c1b6e45).
+ *
+ * Recovery sweep that backfills the engine PR store for shared-branch plans
+ * whose aggregate PR already exists on the remote but was never tracked (or
+ * was tracked without the full `prdItems` linkage). This is the "belt" to the
+ * no-self-PR guards in the playbooks: even if a per-item leak opened a PR, or
+ * the engine missed the aggregate "Create PR for plan" item, this sweep heals
+ * the linkage so the dashboard renders the single aggregate PR
+ * (`countDistinctPrdItems > 1`) instead of N phantom per-item rows.
+ *
+ * Canonical incident: PR #228 (plan minions-opg-2026-06-17.json).
+ *
+ * Invariants:
+ *   - NEVER creates a remote PR (no `gh pr create` / `az repos pr create`).
+ *   - Per-PRD try/catch — one bad plan never aborts the sweep.
+ *   - Idempotent — a fully-linked PRD is a no-op (no mutate, no heal log).
+ *   - Multi-project shared-branch plans heal per-project.
+ *   - Zero new runtime deps (Node built-ins + existing engine modules only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const queries = require('./queries');
+const github = require('./github');
+const ado = require('./ado');
+
+const { log } = shared;
+const PRD_DIR = queries.PRD_DIR;
+
+// Test seam (consumed by P-4e7d2c56): when set, replaces the live remote PR
+// lookup so unit tests can exercise the heal/no-op branches without a network.
+let _remotePrFinderOverride = null;
+function _setRemotePrFinderForTest(fn) {
+  _remotePrFinderOverride = (typeof fn === 'function') ? fn : null;
+}
+
+/** True for an active/completed shared-branch PRD that carries a feature branch. */
+function _isSharedBranchPrd(plan) {
+  return !!plan
+    && plan.branch_strategy === 'shared-branch'
+    && typeof plan.feature_branch === 'string'
+    && plan.feature_branch.trim() !== ''
+    && Array.isArray(plan.missing_features)
+    && plan.status !== 'cancelled';
+}
+
+/** All PRD item ids for a plan — the aggregate linkage set. */
+function _collectPlanItemIds(plan) {
+  const ids = [];
+  for (const item of (plan?.missing_features || [])) {
+    if (item && typeof item.id === 'string' && item.id) ids.push(item.id);
+  }
+  return ids;
+}
+
+/** Distinct project names referenced by a plan (top-level + per-item). */
+function _collectPlanProjectNames(plan) {
+  const names = new Set();
+  if (plan?.project) names.add(plan.project);
+  for (const item of (plan?.missing_features || [])) {
+    if (item?.project) names.add(item.project);
+  }
+  return [...names];
+}
+
+/**
+ * Query the remote for an OPEN PR on feature_branch -> mainRef. Never creates one.
+ *   GitHub: ghApi GET /pulls?head=<owner>:<branch>&base=<main>&state=open.
+ *   ADO:    ado.findOpenPrOnBranch (active PRs by sourceRefName), reusing the
+ *           ado throttle / circuit-breaker plumbing — never raw curl.
+ * Returns { prNumber, url } or null.
+ */
+async function _queryRemoteOpenPr(project, branch, mainRef) {
+  if (_remotePrFinderOverride) return _remotePrFinderOverride(project, branch, mainRef);
+  if (!project || !branch) return null;
+
+  if (github.isGitHub(project)) {
+    const slug = github.getRepoSlug(project);
+    if (!slug) return null;
+    const owner = slug.split('/')[0];
+    // validateGhEndpoint disallows ':' — encode the head separator as %3A and
+    // keep the branch slashes intact (GitHub expects head=<owner>:<branch>).
+    const head = `${owner}%3A${branch}`;
+    const endpoint = `/pulls?head=${head}&base=${encodeURIComponent(mainRef || '')}&state=open`;
+    const data = await github.ghApi(endpoint, slug);
+    const pr = Array.isArray(data) ? data[0] : null;
+    if (!pr || pr.number == null) return null;
+    return { prNumber: pr.number, url: pr.html_url || '' };
+  }
+
+  // ADO (and any non-GitHub host) — findOpenPrOnBranch matches active PRs by
+  // sourceRefName and returns { prNumber, url } or null.
+  return (await ado.findOpenPrOnBranch(project, branch)) || null;
+}
+
+/**
+ * Decide whether the PR store needs healing for this remote PR against a plan's
+ * full item set. Returns { needsHeal, missingIds }.
+ */
+function _evaluateHeal(prs, project, remote, planIds) {
+  const canonicalId = shared.getCanonicalPrId(project, remote.prNumber, remote.url);
+  const record = shared.findPrRecord(prs, { id: canonicalId, prNumber: remote.prNumber, url: remote.url }, project);
+  const linked = new Set(Array.isArray(record?.prdItems) ? record.prdItems : []);
+  const missingIds = planIds.filter(id => !linked.has(id));
+  return { needsHeal: !record || missingIds.length > 0, missingIds };
+}
+
+/** Heal one project's PR store for one shared-branch PRD. */
+async function _reconcilePrdForProject(plan, file, project, planIds) {
+  const mainRef = shared.resolveMainBranch(project.localPath, project.mainBranch);
+  const branch = shared.sanitizeBranch(plan.feature_branch);
+  const remote = await _queryRemoteOpenPr(project, branch, mainRef);
+  if (!remote) return; // no remote PR -> nothing to heal
+
+  const prPath = shared.projectPrPath(project);
+  const { needsHeal } = _evaluateHeal(shared.safeJsonArr(prPath), project, remote, planIds);
+  if (!needsHeal) return; // fully-linked -> idempotent no-op
+
+  // upsertPullRequestRecord MERGES prdItems + calls addPrLink per item, yielding
+  // the aggregate shape (countDistinctPrdItems > 1) the dashboard renders.
+  const result = shared.upsertPullRequestRecord(prPath, {
+    url: remote.url,
+    prNumber: remote.prNumber,
+    branch,
+    _project: project.name,
+    sourcePlan: file,
+    contextOnly: false,
+  }, { project, itemIds: planIds });
+
+  if (result && (result.created || result.linked)) {
+    const n = Array.isArray(result.record?.prdItems) ? result.record.prdItems.length : planIds.length;
+    log('info', `[shared-branch-reconcile] healed PRD ${file} -> registered aggregate PR ${result.id} (prdItems=${n})`);
+  }
+}
+
+/**
+ * Enumerate active/completed shared-branch PRDs and heal the engine PR store
+ * for any whose aggregate remote PR exists but is untracked / under-linked.
+ * Per-PRD and per-project failures are isolated so one bad plan never aborts
+ * the sweep.
+ */
+async function reconcileSharedBranchPrs(config) {
+  let planFiles;
+  try { planFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json')); }
+  catch { return; } // PRD dir absent -> nothing to do
+
+  for (const file of planFiles) {
+    try {
+      const plan = shared.safeJsonNoRestore(path.join(PRD_DIR, file));
+      if (!_isSharedBranchPrd(plan)) continue;
+      const planIds = _collectPlanItemIds(plan);
+      if (planIds.length === 0) continue;
+
+      for (const projName of _collectPlanProjectNames(plan)) {
+        try {
+          const project = shared.resolveProjectSource(projName, config, { allowCentral: false }).project;
+          if (!project) continue;
+          await _reconcilePrdForProject(plan, file, project, planIds);
+        } catch (projErr) {
+          log('warn', `[shared-branch-reconcile] project ${projName} for PRD ${file}: ${projErr?.message || projErr}`);
+        }
+      }
+    } catch (err) {
+      log('warn', `[shared-branch-reconcile] PRD ${file}: ${err?.message || err}`);
+    }
+  }
+}
+
+module.exports = {
+  reconcileSharedBranchPrs,
+  // exported for testing
+  _isSharedBranchPrd,
+  _collectPlanItemIds,
+  _collectPlanProjectNames,
+  _queryRemoteOpenPr,
+  _evaluateHeal,
+  _reconcilePrdForProject,
+  _setRemotePrFinderForTest,
+};

package/engine/shared.js

@@ -6882,12 +6882,22 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
 //
 // Per-record decision:
 //   1. contextOnly := (_contextOnly === true)
-//   2. legacyManaged := prdItems.length > 0 || _autoObserve === true ||
-//                       sourcePlan || itemType || (agent is a Minions persona)
-//      "Minions persona" = non-empty kebab-case identifier other than 'human'.
-//      Anything with whitespace (human display names like "yemi shin", which
-//      github poller writes into `agent` from `prData.user.login`) is treated
-//      as a human author, not a managed agent.
+//   2. legacyManaged := _autoObserve === true || sourcePlan || itemType ||
+//                       (agent is a *configured* Minions persona)
+//      "Configured Minions persona" = `agent` matches an id in
+//      `config.agents` (case-insensitive). The github poller writes the PR
+//      author's login into `agent` (from `prData.user.login`); human logins
+//      like `calebt_microsoft` are kebab/snake-shaped and previously passed a
+//      naive shape regex, mis-classifying a human PR as managed and flipping
+//      its observe toggle ON on the next boot (W-mqil3jtw). Cross-checking the
+//      real roster instead of a shape heuristic fixes that. A login that is
+//      not a configured agent id is treated as a human author.
+//      NOTE: `prdItems.length > 0` is intentionally NOT a managed signal in
+//      this migration. A watch can link a PR context-only AND spin off a
+//      courtesy-review WI whose id is stamped into `prdItems`; that stamp must
+//      not override the explicit context-only intent. Genuine managed PRs
+//      always carry a real signal above (configured agent / sourcePlan /
+//      itemType / _autoObserve), so dropping prdItems-alone is safe here.
 //   3. If !contextOnly && !legacyManaged, set contextOnly = true and stamp
 //      `_migrationNote: 'auto-set-contextOnly-by-pr-gate-simplification'`.
 //   4. Persist `contextOnly`; delete `_autoObserve`, `_manual`, `_contextOnly`.
@@ -6903,22 +6913,49 @@ function _prRecordHasLegacyGateKey(record) {
     || Object.prototype.hasOwnProperty.call(record, '_manual');
 }
 
-function _prRecordIsLegacyManaged(record) {
-  const prdItemsCount = Array.isArray(record.prdItems) ? record.prdItems.length : 0;
-  if (prdItemsCount > 0) return true;
+// Resolve the configured agent roster (lower-cased Set) once per migration.
+// Accepts either an explicit `agentIds` (Set / array) or a `config` object
+// whose `agents` keys are the roster. Returns an empty Set when nothing is
+// supplied (no record can match a managed persona).
+// (Deliberately NOT queries.getAgents(config): that lives in queries.js — which
+// requires shared.js, so importing it here is circular — and it also reads
+// dispatch/inbox state. We only need the bare id set.)
+function _resolveConfiguredAgentIds(opts = {}) {
+  let ids = opts.agentIds;
+  if (ids == null && opts.config && opts.config.agents && typeof opts.config.agents === 'object') {
+    ids = Object.keys(opts.config.agents);
+  }
+  const source = ids instanceof Set ? [...ids] : (Array.isArray(ids) ? ids : []);
+  return new Set(source.map(id => String(id || '').trim().toLowerCase()).filter(Boolean));
+}
+
+// `agentIds` (a Set, supplied by the boot migration) switches this helper into
+// "roster mode": the `agent` field only counts as a managed signal when it is
+// an actually-configured agent id, and prdItems-alone is dropped (see the
+// migration header). Callers that can't cheaply resolve the roster (the
+// runtime upsert/link demotion-guard at the `_prRecordIsLegacyManaged(target)`
+// call site) pass no agentIds and keep the legacy shape-heuristic behavior.
+function _prRecordIsLegacyManaged(record, agentIds) {
+  const rosterMode = agentIds instanceof Set;
+  // prdItems-alone is a managed signal only in the legacy runtime path, not the
+  // boot migration (see header: courtesy-review watch contamination).
+  if (!rosterMode && Array.isArray(record.prdItems) && record.prdItems.length > 0) return true;
   if (record._autoObserve === true) return true;
   if (record.sourcePlan) return true;
   if (record.itemType) return true;
   if (typeof record.agent === 'string') {
     const agent = record.agent.trim().toLowerCase();
-    if (agent && agent !== 'human' && _AGENT_PERSONA_RE.test(agent)) return true;
+    if (agent && agent !== 'human') {
+      if (rosterMode ? agentIds.has(agent) : _AGENT_PERSONA_RE.test(agent)) return true;
+    }
   }
   return false;
 }
 
-function migratePrGateFlags(projectsRoot) {
+function migratePrGateFlags(projectsRoot, opts = {}) {
   const summary = { projectsScanned: 0, projectsMigrated: 0, totalRecords: 0, totalMigrated: 0 };
   if (!projectsRoot || typeof projectsRoot !== 'string') return summary;
+  const agentIds = _resolveConfiguredAgentIds(opts);
   let entries;
   try {
     entries = fs.readdirSync(projectsRoot, { withFileTypes: true });
@@ -6945,7 +6982,7 @@ function migratePrGateFlags(projectsRoot) {
         if (hasCanonical && !hasLegacy) { alreadyMigrated++; continue; }
 
         let contextOnly = (record._contextOnly === true);
-        if (!contextOnly && !_prRecordIsLegacyManaged(record)) {
+        if (!contextOnly && !_prRecordIsLegacyManaged(record, agentIds)) {
           contextOnly = true;
           record._migrationNote = _PR_GATE_MIGRATION_NOTE;
           stamped++;

package/engine.js

@@ -5026,6 +5026,7 @@ function reconcileItemsWithPrs(items, allPrs, { onlyIds } = {}) {
 const { consolidateInbox } = require('./engine/consolidation');
 const { pollPrStatus, pollPrHumanComments, reconcilePrs, checkLiveReviewStatus: adoCheckLiveReview, checkLiveBuildAndConflict: adoCheckLiveBuildAndConflict, needsAdoPollRetry, getAdoToken, isAdoThrottled, getAdoThrottleStateAll } = require('./engine/ado');
 const { pollPrStatus: ghPollPrStatus, pollPrHumanComments: ghPollPrHumanComments, reconcilePrs: ghReconcilePrs, checkLiveReviewStatus: ghCheckLiveReview, checkLiveBuildAndConflict: ghCheckLiveBuildAndConflict, isGhThrottled } = require('./engine/github');
+const { reconcileSharedBranchPrs } = require('./engine/shared-branch-pr-reconcile');
 
 // ─── State Snapshot ─────────────────────────────────────────────────────────
 
@@ -6881,6 +6882,10 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // implement→implement-shared gate at engine/playbook.js). Default '' for
     // parallel/PR-targeted dispatches keeps existing per-type PR behavior.
     shared_branch: (item.branchStrategy === 'shared-branch' && item.featureBranch) ? '1' : '',
+    // Optional: the canonical shared-branch name so any playbook can reference
+    // {{feature_branch}} without a second source of truth. Resolves to
+    // item.featureBranch for shared-branch work-item dispatches; '' otherwise.
+    feature_branch: item.featureBranch || '',
     notes_content: '',
     pr_id: item.pr_id || item._pr || item.targetPr || item.sourcePr || item.pr || '',
     pr_number: item.prNumber || item.pr_number || '',
@@ -9098,6 +9103,20 @@ async function tickInner() {
     } catch (err) {
       log('warn', `[pull-requests] scope-mismatch sweep error: ${err?.message || err}`);
     }
+
+    // P-6b3a9f78 — Shared-branch PR reconciler (recovery sweep). Backfills the
+    // engine PR store for shared-branch plans whose aggregate remote PR exists
+    // but is untracked / under-linked, so the dashboard renders the single
+    // aggregate PR instead of N phantom per-item rows. Host-agnostic and fully
+    // self-guarding (per-PRD/per-project try/catch, never creates a remote PR),
+    // so it runs unconditionally in the reconcile phase like the other recovery
+    // sweeps — independent of the ADO/GitHub poll + throttle gates.
+    try {
+      await reconcileSharedBranchPrs(config);
+    } catch (err) {
+      log('warn', `[shared-branch-reconcile] sweep error: ${err?.message || err}`);
+    }
+    if (_isTickStale(myGeneration)) return;
   }
 
   // 2.9. Stalled dispatch detection — auto-retry failed items blocking the graph (~20 min — cadence in ENGINE_DEFAULTS.stalledDispatchSweepEvery)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2218",
+  "version": "0.1.2219",
   "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/fix.md

@@ -84,6 +84,23 @@ Long builds, dependency installs, and tests may be quiet for several minutes. Le
 
 ## Publish & Comment on PR
 
+{{#shared_branch}}
+This is part of a **shared-branch plan** — other plan items share `{{branch_name}}`.
+After the fix is validated or any unavoidable limitation is clearly documented, commit only relevant files and push to the shared branch:
+
+```bash
+git add <specific files>
+git commit -m "fix: address review feedback on {{pr_id}}"
+git push origin {{branch_name}}
+```
+
+Push your commit to the shared branch and STOP. Do **NOT** create a PR — the engine
+opens one aggregate PR automatically when all plan items complete. Opening a PR now
+would be premature (other items are still in flight) and the early branch would collect
+merge conflicts from concurrent sibling pushes. Posting review/fix **comments** on an
+existing PR is still fine. Do NOT remove the worktree — the engine handles cleanup automatically.
+{{/shared_branch}}
+{{^shared_branch}}
 After the fix is validated or any unavoidable limitation is clearly documented, commit only relevant files and push:
 
 ```bash
@@ -98,6 +115,7 @@ Do NOT remove the worktree — the engine handles cleanup automatically.
 - pullRequestId: `{{pr_number}}`
 - content: Explain what was fixed, reference each review finding, include build/test status
 - Sign: `Fixed by Minions ({{agent_name}} — {{agent_role}} · {{agent_model}})`
+{{/shared_branch}}
 
 ## PR description audit (mandatory unless `meta.skipDescriptionAudit`)
 

package/playbooks/implement.md

@@ -87,6 +87,22 @@ Long builds, dependency installs, and tests may be quiet for several minutes. Le
 
 ## Publish
 
+{{#shared_branch}}
+This is part of a **shared-branch plan** — other plan items share `{{branch_name}}`.
+After the change is validated or any unavoidable limitation is clearly documented, commit only the relevant files and push to the shared branch:
+
+```bash
+git add <specific files>
+git commit -m "{{commit_message}}"
+git push origin {{branch_name}}
+```
+
+Push your commit to the shared branch and STOP. Do **NOT** create a PR — the engine
+opens one aggregate PR automatically when all plan items complete. Opening a PR now
+would be premature (other items are still in flight) and the early branch would collect
+merge conflicts from concurrent sibling pushes.
+{{/shared_branch}}
+{{^shared_branch}}
 After the change is validated or any unavoidable limitation is clearly documented, commit only the relevant files and push this branch:
 
 ```bash
@@ -100,6 +116,7 @@ git push -u origin {{branch_name}}
 Create the PR for implement tasks — the engine tracks review and completion from the PR.
 
 Include build/test status and run instructions in the PR description. If the project has a runnable app, include the localhost URL.
+{{/shared_branch}}
 
 ## PR description audit (mandatory unless `meta.skipDescriptionAudit`)
 
@@ -174,6 +191,11 @@ Omit `meta.descriptionAudit` entirely when the audit did not run (no commits pus
 
 ## When to Stop
 
+{{#shared_branch}}
+Your task is complete when the requested implementation is delivered, the validation story is truthful and sufficient for review, and your commit is pushed to the shared branch `{{branch_name}}`. Do NOT create a PR — the engine creates one when all plan items are done.
+{{/shared_branch}}
+{{^shared_branch}}
 Your task is complete when the requested implementation is delivered, the validation story is truthful and sufficient for review, the branch is pushed, and the PR exists. Include the PR URL in your final message so the engine can track it.
+{{/shared_branch}}
 
 Do NOT run `gh pr merge` or any other merge command on your own PR. The engine reviews and merges PRs through a separate review cycle. Self-merging is prohibited.

package/playbooks/shared-rules.md

@@ -75,7 +75,11 @@ For a `type: "fix"` work item that targets an existing PR, the engine reuses the
 
 If you are running a fix task and `{{pr_branch}}` is populated, your worktree is already on that branch — push the fix commit there and do **not** create a new PR. If `{{pr_branch}}` is empty but the task description / references clearly point at an existing PR, **stop** and emit a non-retryable completion (`failure_class: 'branch-mismatch'`) instead of branching off master and opening a duplicate PR. See issue #2999 for the canonical bad incident (ADO PR `!5284819` → duplicate `!5288540`).
 
-## Engine Rules (apply to all tasks)
+{{#shared_branch}}## Shared-Branch Plan — No Self-PR (READ FIRST)
+
+This task is part of a **shared-branch plan** — every plan item shares the branch `{{branch_name}}`. Commit your focused changes and push them to that branch (`git push origin {{branch_name}}`), then STOP. Do **NOT** create a PR — do **not** run `gh pr create` or `az repos pr create`. The engine opens ONE aggregate PR automatically when all plan items complete; creating a PR now would be premature and the early branch would collect merge conflicts from concurrent sibling pushes. Posting review/fix **comments** on existing PRs is still fine.
+
+{{/shared_branch}}## Engine Rules (apply to all tasks)
 
 **Context compaction:** Your context window may be compacted mid-task by Claude's infrastructure. If you notice your earlier conversation history appears truncated or summarized, this is normal and expected. Do not interpret compaction as a signal to stop early or wrap up. Continue working toward your task objective — all relevant instructions and state remain available.
 
@@ -294,7 +298,7 @@ So write `Fixed by [Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/m
 
 ## GitHub Tooling and Auth
 
-For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as `gh pr create`, `gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`. **For comment / review posts, always go through `minions pr comment` or include the marker template above.**
+For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as {{^shared_branch}}`gh pr create`, {{/shared_branch}}`gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`. **For comment / review posts, always go through `minions pr comment` or include the marker template above.**
 
 If GitHub or Copilot auth fails, check GitHub/Copilot credentials only:
 - `gh auth status`
@@ -332,7 +336,7 @@ Output is JSON with the same fields. Exit 0 on success, 1 if not found.
 
 ## Azure DevOps Tooling
 
-For Azure DevOps repo operations, use the `az` CLI first. Prefer commands such as `az repos pr create`, `az repos pr show`, `az repos pr list`, `az repos pr comment`, `az repos pr reviewer`, `az boards work-item`, and `az pipelines` after setting defaults with `az devops configure`.
+For Azure DevOps repo operations, use the `az` CLI first. Prefer commands such as {{^shared_branch}}`az repos pr create`, {{/shared_branch}}`az repos pr show`, `az repos pr list`, `az repos pr comment`, `az repos pr reviewer`, `az boards work-item`, and `az pipelines` after setting defaults with `az devops configure`.
 
 If `az` is unavailable or insufficient for a specific operation (e.g. PR comment threads on an older az-devops extension), fall back to the ADO REST API directly: acquire a token with `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv` and call the `_apis/git/...` endpoints with Bearer auth. Do not use `gh` for Azure DevOps repositories.
 {{/ado_shared_rules}}

package/playbooks/verify.md

@@ -49,6 +49,8 @@ Use the template at `{{team_root}}/playbooks/templates/verify-guide.md` and clea
 
 ## E2E PRs
 
+<!-- Intentionally NOT guarded by {{^shared_branch}}: verify.md is the legitimate aggregate/E2E PR creator that opens the single plan-completion PR. Do not add a shared-branch no-self-PR guard here (P-5a6e8b21). -->
+
 For each project with aggregate verification changes, create or update one draft/review PR that combines the plan branches into a single reviewable diff. Reuse an existing `e2e/{{plan_slug}}` branch/PR when present. Include the plan summary, merged PRs, testing guide, and build/test status. Do not auto-complete or merge these PRs.
 
 Track each E2E PR in the project's `.minions/pull-requests.json` if it is not already tracked.

package/playbooks/work-item.md

@@ -37,6 +37,22 @@ Treat this like the user typed the task directly into a CLI agent:
 - Do NOT publish code with a broken build or failing tests that you introduced.
 - Long builds and tests may be quiet for several minutes. Let normal CLI commands run without artificial heartbeat output.
 
+{{#shared_branch}}
+After the change is ready for review, commit only relevant files and push to the shared branch:
+
+```bash
+git add <specific files>
+git commit -m "feat({{item_id}}): <description>"
+git push origin {{branch_name}}
+```
+
+This is part of a **shared-branch plan** — other plan items share `{{branch_name}}`.
+Push your commit to the shared branch and STOP. Do **NOT** create a PR — the engine
+opens one aggregate PR automatically when all plan items complete. Opening a PR now
+would be premature (other items are still in flight) and the early branch would collect
+merge conflicts from concurrent sibling pushes.
+{{/shared_branch}}
+{{^shared_branch}}
 After the change is ready for review, commit only relevant files, push `{{branch_name}}`, create the PR, and post implementation notes with the validation result:
 
 ```bash
@@ -51,12 +67,18 @@ git push -u origin {{branch_name}}
 - title: `feat({{item_id}}): <description>`
 
 {{pr_comment_instructions}}
+{{/shared_branch}}
 
 Do NOT remove the worktree — the engine handles cleanup automatically.
 
 ## After Successful Completion
 
+{{#shared_branch}}
+Write your findings to `{{team_root}}/notes/inbox/{{agent_id}}-{{item_id}}-{{date}}.md` only after the work item succeeds: build/tests pass and the branch is pushed to the shared branch. Do NOT create a PR — the engine opens one when all plan items complete.
+{{/shared_branch}}
+{{^shared_branch}}
 Write your findings to `{{team_root}}/notes/inbox/{{agent_id}}-{{item_id}}-{{date}}.md` only after the work item succeeds: build/tests pass, the branch is pushed, and the PR is created.
+{{/shared_branch}}
 
 If you stop because the task failed, is blocked, or is only partially complete, do **not** write an inbox note. Put the failure details in your final response and in any required PR/work-item comment instead.
 
@@ -68,6 +90,11 @@ If you encounter merge conflicts during push or PR creation:
 
 ## When to Stop
 
+{{#shared_branch}}
+Your task is complete when the requested work item is delivered, the validation story is truthful and sufficient for review, and your commit is pushed to the shared branch `{{branch_name}}`. Do NOT create a PR — the engine creates one when all plan items are done. Do NOT continue into unrelated improvements.
+{{/shared_branch}}
+{{^shared_branch}}
 Your task is complete when the requested work item is delivered, the validation story is truthful and sufficient for review, the branch is pushed, and the PR exists. Do NOT continue into unrelated improvements.
+{{/shared_branch}}
 
 Do NOT run `gh pr merge` or any other merge command on your own PR. The engine reviews and merges PRs through a separate review cycle. Self-merging is prohibited.