@yemi33/minions 0.1.1999 → 0.1.2000

package/dashboard/js/render-prs.js

@@ -4,6 +4,24 @@ let allPrs = [];
 let prPage = 0;
 const PR_PER_PAGE = 25;
 
+function _countPrFollowups(pr) {
+  // PR follow-up chip (W-mpej3cox00099466) — counts WIs whose
+  // meta.pr_followup.parent_pr_url or parent_pr_id matches this PR.
+  if (!pr) return 0;
+  var wis = (window._lastWorkItems) || [];
+  if (!wis.length) return 0;
+  var prUrl = pr.url || '';
+  var prId = pr.id || '';
+  var n = 0;
+  for (var i = 0; i < wis.length; i++) {
+    var f = wis[i] && wis[i].meta && wis[i].meta.pr_followup;
+    if (!f) continue;
+    if (prUrl && f.parent_pr_url === prUrl) { n++; continue; }
+    if (prId && f.parent_pr_id === prId) { n++; }
+  }
+  return n;
+}
+
 function prRow(pr) {
   // Minions review (agent) state — separate from ADO human review
   const sq = pr.minionsReview || {};
@@ -27,9 +45,13 @@ function prRow(pr) {
   const pendingReasonHtml = pendingReason
     ? '<div style="font-size:9px;color:var(--muted);margin-top:2px" title="Pending reason: ' + escapeHtml(pendingReason) + '">' + escapeHtml(pendingReason.replace(/_/g, ' ')) + '</div>'
     : '';
+  var followupCount = _countPrFollowups(pr);
+  var followupChip = followupCount > 0
+    ? ' <span class="pr-badge draft" style="font-size:8px" title="' + followupCount + ' follow-up work item(s) dispatched from comments on this PR">+' + followupCount + ' follow-up' + (followupCount === 1 ? '' : 's') + '</span>'
+    : '';
   return '<tr>' +
     '<td><span class="pr-id">' + escapeHtml(String(prId)) + '</span></td>' +
-    '<td><a class="pr-title" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(pr.title || 'Untitled') + '</a>' + (pr.description ? '<div class="pr-desc">' + escapeHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
+    '<td><a class="pr-title" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(pr.title || 'Untitled') + '</a>' + followupChip + (pr.description ? '<div class="pr-desc">' + escapeHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
     '<td><span class="pr-agent">' + escapeHtml(pr.agent || '—') + '</span></td>' +
     '<td><span class="' + branchClass + '"' + (branchError ? ' title="' + escapeHtml(branchError) + '"' : '') + '>' + escapeHtml(branchLabel) + '</span>' + pendingReasonHtml + '</td>' +
     '<td><span class="pr-badge ' + reviewClass + '"' + (reviewTitle ? ' title="' + escapeHtml(reviewTitle) + '"' : '') + '>' + escapeHtml(reviewLabel) + '</span></td>' +

package/dashboard/js/render-work-items.js

@@ -40,9 +40,19 @@ function wiRow(item) {
     : (item.branchStrategy === 'shared-branch' && item.status === 'done')
       ? '<span style="font-size:9px;color:var(--muted)" title="Part of shared branch — aggregate PR created at verify stage">shared branch</span>'
       : '<span style="color:var(--muted)">—</span>';
+  // PR follow-up chip (W-mpej3cox00099466) — surfaced when the WI was spun
+  // off from a PR comment via meta.pr_followup. Links to the parent PR.
+  var prFollowup = item.meta && item.meta.pr_followup;
+  var followupChip = '';
+  if (prFollowup && prFollowup.parent_pr_url) {
+    var prRef = prFollowup.parent_pr_id || prFollowup.parent_pr_url;
+    var prNumMatch = String(prRef).match(/(\d+)(?!.*\d)/);
+    var prLabel = prNumMatch ? ('PR #' + prNumMatch[1]) : 'parent PR';
+    followupChip = ' <a class="pr-badge draft" style="font-size:8px;text-decoration:none" target="_blank" rel="noopener" href="' + escapeHtml(prFollowup.parent_pr_url) + '" title="Follow-up dispatched from ' + escapeHtml(prRef) + (prFollowup.parent_comment_author ? ' by ' + escapeHtml(prFollowup.parent_comment_author) : '') + '" onclick="event.stopPropagation()">&#8617; from ' + escapeHtml(prLabel) + '</a>';
+  }
   return '<tr data-wi-id="' + escapeHtml(item.id) + '" style="cursor:pointer" onclick="if(shouldIgnoreSelectionClick(event))return;openWorkItemDetail(\'' + escapeHtml(item.id) + '\')">' +
     '<td><span class="pr-id">' + escapeHtml(item.id || '') + '</span></td>' +
-    '<td style="max-width:220px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escapeHtml((item.title || '').slice(0, 200)) + '">' + escapeHtml(item.title || '') + '</td>' +
+    '<td style="max-width:220px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escapeHtml((item.title || '').slice(0, 200)) + '">' + escapeHtml(item.title || '') + followupChip + '</td>' +
     '<td><span style="font-size:10px;color:var(--muted)">' + escapeHtml(item._source || '') + '</span>' +
       (item.scope === 'fan-out' ? ' <span class="pr-badge ' + (item.status === 'done' || item.status === 'failed' ? 'draft' : 'building') + '" style="font-size:8px">fan-out</span>' : '') + '</td>' +
     '<td>' + typeBadge(item.type) + '</td>' +

package/dashboard.js

@@ -281,6 +281,62 @@ function copyWorkItemPrFields(item, input, pr = null) {
   if (pr?.url || input.prUrl) item.prUrl = pr?.url || input.prUrl;
 }
 
+// ─── PR follow-up dispatch (W-mpej3cox00099466) ─────────────────────────────
+// Validates the meta.pr_followup shape and enforces parent_comment_id-keyed
+// dedup across the project's work-items so retries from the fix/review agent
+// (or two pollers racing) don't fan out duplicate follow-up WIs. See
+// playbooks/templates/followup-dispatch.md and docs/pr-comment-followup.md.
+
+const PR_FOLLOWUP_REQUIRED_FIELDS = ['parent_pr_url', 'parent_pr_id', 'parent_comment_id', 'parent_comment_author'];
+const PR_FOLLOWUP_MAX_FIELD_LEN = 512;
+
+function validatePrFollowupShape(value) {
+  if (value === undefined || value === null) return { valid: true, value: null };
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return { valid: false, error: 'meta.pr_followup must be an object with parent_pr_url, parent_pr_id, parent_comment_id, parent_comment_author (strings)' };
+  }
+  const cleaned = {};
+  for (const field of PR_FOLLOWUP_REQUIRED_FIELDS) {
+    const raw = value[field];
+    if (typeof raw !== 'string' || !raw.trim()) {
+      return { valid: false, error: `meta.pr_followup.${field} is required and must be a non-empty string` };
+    }
+    if (raw.length > PR_FOLLOWUP_MAX_FIELD_LEN) {
+      return { valid: false, error: `meta.pr_followup.${field} exceeds ${PR_FOLLOWUP_MAX_FIELD_LEN} characters` };
+    }
+    cleaned[field] = raw.trim();
+  }
+  return { valid: true, value: cleaned };
+}
+
+function findExistingFollowupForComment(items, parentCommentId) {
+  if (!Array.isArray(items) || !parentCommentId) return null;
+  const needle = String(parentCommentId).trim();
+  if (!needle) return null;
+  return items.find(item => {
+    const seen = item?.meta?.pr_followup?.parent_comment_id;
+    return typeof seen === 'string' && seen.trim() === needle;
+  }) || null;
+}
+
+function extractMinionsAgentHeader(req) {
+  const raw = req?.headers?.['x-minions-agent'];
+  if (typeof raw !== 'string') return '';
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed.length > 128) return '';
+  // Restrict to safe characters; agent ids are kebab-case or `temp-…`.
+  return /^[A-Za-z0-9._:-]+$/.test(trimmed) ? trimmed : '';
+}
+
+function extractMinionsOriginWiHeader(req) {
+  const raw = req?.headers?.['x-minions-origin-wi'];
+  if (typeof raw !== 'string') return '';
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed.length > 128) return '';
+  return /^[A-Za-z0-9._:-]+$/.test(trimmed) ? trimmed : '';
+}
+
+
 function normalizeWorkItemDedupText(value) {
   return String(value == null ? '' : value)
     .replace(/\r\n/g, '\n')
@@ -4681,9 +4737,25 @@ const server = http.createServer(async (req, res) => {
       // meta.keep_processes documentation in prompts/cc-system.md and
       // the documented `meta?` /api/routes parameter would silently no-op.
       // Shallow copy of plain objects only — arrays/null/primitives are dropped.
+      let validatedFollowup = null;
       if (body.meta && typeof body.meta === 'object' && !Array.isArray(body.meta)) {
+        // PR follow-up validation (W-mpej3cox00099466) — verify meta.pr_followup
+        // shape BEFORE the WI is written so a malformed sidecar can't slip in.
+        const followupCheck = validatePrFollowupShape(body.meta.pr_followup);
+        if (!followupCheck.valid) {
+          return jsonReply(res, 400, { error: followupCheck.error });
+        }
         item.meta = { ...body.meta };
+        if (followupCheck.value) {
+          item.meta.pr_followup = followupCheck.value;
+          validatedFollowup = followupCheck.value;
+        }
       }
+      // PR follow-up traceability headers (W-mpej3cox00099466).
+      const originAgent = extractMinionsAgentHeader(req);
+      const originWi = extractMinionsOriginWiHeader(req);
+      if (originAgent) item._originAgent = originAgent;
+      if (originWi) item._originWi = originWi;
       copyWorkItemPrFields(item, body);
       // W-mpejf0fq000e84d6: pre-compute the canonical branch name at create
       // time so the persisted WI carries `branch` from the moment it hits
@@ -4698,6 +4770,28 @@ const server = http.createServer(async (req, res) => {
           if (derived) item.branch = derived;
         } catch (e) { /* identity resolver best-effort; engine will derive on dispatch */ }
       }
+      // PR follow-up parent_comment_id dedup (W-mpej3cox00099466) — must run
+      // inside the same lock as createWorkItemWithDedup so a racing pair of
+      // pollers/agents can't both win. Standard title/type/project dedup runs
+      // afterward; the follow-up check is stricter (project-wide, all
+      // statuses) and takes precedence when matched.
+      if (validatedFollowup) {
+        let followupConflict = null;
+        mutateWorkItems(wiPath, items => {
+          followupConflict = findExistingFollowupForComment(items, validatedFollowup.parent_comment_id);
+          if (followupConflict) return items;
+          items.push(item);
+          return items;
+        });
+        if (followupConflict) {
+          return jsonReply(res, 409, {
+            error: 'followup_already_dispatched',
+            existingWiId: followupConflict.id,
+          });
+        }
+        recordCcTurnIfPresent(req, { kind: 'work-item', id, title: item.title, project: item.project || null });
+        return jsonReply(res, 200, { ok: true, id });
+      }
       const createResult = createWorkItemWithDedup(wiPath, item);
       if (!createResult.created) {
         const duplicateId = createResult.duplicateOf || createResult.item?.id;
@@ -9112,7 +9206,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'DELETE', path: /^\/api\/qa\/runbooks\/([^/?]+)$/, template: '/api/qa/runbooks/<id>', desc: 'Delete a QA runbook by id.', handler: handleQaRunbooksDelete },
 
     // Work items
-    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?', handler: handleWorkItemsCreate },
+    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?, meta.pr_followup?, X-Minions-Agent?, X-Minions-Origin-Wi?', handler: handleWorkItemsCreate },
     { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?', handler: handleWorkItemsUpdate },
     { method: 'POST', path: '/api/work-items/retry', desc: 'Reset a failed/dispatched item to pending', params: 'id, source?', handler: handleWorkItemsRetry },
     { method: 'POST', path: '/api/work-items/delete', desc: 'Remove a work item, kill agent, clear dispatch', params: 'id, source?', handler: handleWorkItemsDelete },
@@ -9925,6 +10019,10 @@ module.exports = {
   _findDuplicateWorkItemCreate: findDuplicateWorkItemCreate,
   _createWorkItemWithDedup: createWorkItemWithDedup,
   _resolveWorkItemsCreateTarget: resolveWorkItemsCreateTarget,
+  _validatePrFollowupShape: validatePrFollowupShape,
+  _findExistingFollowupForComment: findExistingFollowupForComment,
+  _extractMinionsAgentHeader: extractMinionsAgentHeader,
+  _extractMinionsOriginWiHeader: extractMinionsOriginWiHeader,
   _buildPlanWorkItem: buildPlanWorkItem,
   _buildManualPrdItemPlan: buildManualPrdItemPlan,
   _resolveScheduleProjectValue: resolveScheduleProjectValue,

package/docs/completion-reports.md

@@ -83,6 +83,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
+| `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
 
 ## `failure_class` enum
 
@@ -129,6 +130,38 @@ Engine behavior when `noop: true` (`engine/lifecycle.js` `parseCompletionNoop` +
 
 Without `noop: true`, an empty PR field will be flagged as a missing-PR-attachment failure and auto-retried up to `ENGINE_DEFAULTS.maxRetries` times.
 
+## PR-comment follow-ups
+
+Fix and review agents can spin off new Minions work items in response to PR
+comments that request **legitimate but out-of-scope** work. See
+`playbooks/templates/followup-dispatch.md` for the full contract (decision
+tree, exact `POST /api/work-items` shape, and required `meta.pr_followup`
+fields). When the agent does so, it MUST record the dispatched WIs in the
+optional `followups` array on its completion report:
+
+```json
+{
+  "status": "success",
+  "summary": "Fixed reviewer's blocking finding on PR #2400; dispatched W-mp9abcdef as out-of-scope follow-up.",
+  "pr": "https://github.com/yemi33/minions/pull/2400",
+  "followups": [
+    {
+      "wi_id": "W-mp9abcdef",
+      "title": "Extract markdown sanitizer into shared module",
+      "reason": "Reviewer asked to track as separate WI (out of scope for #2400 — see comment 4567890)",
+      "parent_comment_id": "4567890"
+    }
+  ]
+}
+```
+
+Engine behavior (`engine/lifecycle.js` `processCompletionFollowups`):
+
+- Each entry is logged at `info`: `Followup audit (<agent> wi=<parent>): dispatched <wi_id> — <title> (comment=<id>) — <reason>`.
+- If the claimed `wi_id` does not exist in any project's `work-items.json` at parse time, a `warn` is emitted. This catches dispatches that were deduped to a 409 / 200-duplicate response, reverted, or never actually landed.
+- The `followups` array is **descriptive only** — the engine does not auto-create or auto-link these WIs from the report. Creation happens at the moment the agent calls `POST /api/work-items`; the report is just the auditable record.
+- Malformed entries (non-object, missing `wi_id`) are logged and skipped.
+
 ## `retryable` and `needs_rerun`
 
 Both default to `false`. Together they let the agent override the engine's default retry policy:

package/docs/pr-comment-followup.md

@@ -0,0 +1,206 @@
+# PR-Comment Follow-up Dispatch
+
+Status: shipped in **W-mpej3cox00099466** (replaces the marker-based "Option A"
+proposal investigated in CC turn `cct-mpeira1y0001ddff`).
+
+## Why
+
+`engine/{github,ado}.js` `pollPrHumanComments` routes every actionable human PR
+comment into `pr.humanFeedback.pendingFix:true`, which `discover-from-prs`
+turns into a `fix` dispatch on the **same** branch. The `fix.md` playbook then
+forbids broadening the PR or creating a replacement branch. The net result was
+a binary outcome for every comment:
+
+1. **In-scope** → fix on the current branch, push, reply on the thread.
+2. **Out of scope / invalid / harmful** → post a rebuttal, leave the thread
+   open, do not change code.
+
+There was no third option for the common case: *"Yes, this is a real ask, but
+it doesn't belong in this PR — track it as a separate WI."* Agents either
+silently rebutted those comments (frustrating reviewers) or broadened the PR
+(making it un-reviewable).
+
+This is **Option B** from the CC investigation: agent judgment + a documented
+playbook contract. The poller is unchanged; the carve-out is purely additive.
+
+## End-to-end walkthrough
+
+1. **Human leaves a comment on PR #2400** asking for a related-but-distinct
+   refactor: *"Can you also extract the markdown sanitizer into a shared module?
+   Probably worth a separate PR though."*
+2. **Engine pollers** (`engine/github.js` `pollPrHumanComments`) flag the
+   comment, set `pr.humanFeedback.pendingFix:true`, and `discover-from-prs`
+   queues a `fix` dispatch against PR #2400's branch.
+3. **Fix agent (e.g. lambert)** starts working. After fetching the diff and
+   the comment, it classifies each ask using the decision tree in
+   `playbooks/templates/followup-dispatch.md`:
+   - The in-scope comments → fix on this branch.
+   - The "extract sanitizer" comment → **follow-up**.
+4. **Follow-up dispatch.** The agent calls the dashboard API with the four
+   `meta.pr_followup` fields and the two identification headers:
+   ```bash
+   curl -sS -X POST http://localhost:7331/api/work-items \
+     -H 'Content-Type: application/json' \
+     -H 'X-Minions-Agent: lambert' \
+     -H 'X-Minions-Origin-Wi: W-mp7originalwi' \
+     -d '{
+       "title": "Extract markdown sanitizer into shared module",
+       "type": "implement",
+       "priority": "medium",
+       "project": "minions",
+       "description": "Reviewer asked to track separately from PR #2400…",
+       "references": [
+         {"url": "https://github.com/yemi33/minions/pull/2400", "label": "Originated from PR #2400 comment"}
+       ],
+       "meta": {
+         "pr_followup": {
+           "parent_pr_url": "https://github.com/yemi33/minions/pull/2400",
+           "parent_pr_id":  "github:yemi33/minions#2400",
+           "parent_comment_id": "4567890",
+           "parent_comment_author": "alice"
+         }
+       }
+     }'
+   ```
+5. **Server (`dashboard.js handleWorkItemsCreate`)**:
+   - Validates `meta.pr_followup` shape (all four fields required, ≤ 512
+     chars each). Malformed → `400 { error: "<message>" }`.
+   - Checks for an existing follow-up with the same `parent_comment_id` in
+     the target project's `work-items.json`. Duplicate → `409 {
+     error: "followup_already_dispatched", existingWiId: "W-…" }` (no second WI
+     created).
+   - Persists the validated `meta.pr_followup`, and stores
+     `X-Minions-Agent` / `X-Minions-Origin-Wi` as `_originAgent` /
+     `_originWi` on the WI for the dashboard timeline.
+   - Returns `200 { ok: true, id: "W-mp9abcdef" }`.
+6. **Reply on the thread.** The agent posts a comment on the original PR
+   thread:
+   > Tracked as follow-up: **W-mp9abcdef** — see the Minions dashboard.
+   > Continuing with the in-place fix on this PR.
+
+   …and resolves that sub-thread. The rest of the PR review proceeds.
+7. **Dashboard chips.**
+   - The new WI's row shows `↪ from PR #2400`, linking back to the parent PR.
+     (`dashboard/js/render-work-items.js` `prFollowup` block.)
+   - The PR row for #2400 shows `+1 follow-up`, computed live from
+     `window._lastWorkItems` and rendered in
+     `dashboard/js/render-prs.js _countPrFollowups`.
+8. **Completion report.** When the fix agent finishes its in-place work and
+   writes the completion JSON, it includes a `followups` array:
+   ```json
+   {
+     "status": "success",
+     "summary": "Fixed reviewer's blocking finding; dispatched W-mp9abcdef as out-of-scope follow-up.",
+     "pr": "https://github.com/yemi33/minions/pull/2400",
+     "followups": [
+       {
+         "wi_id": "W-mp9abcdef",
+         "title": "Extract markdown sanitizer into shared module",
+         "reason": "Out-of-scope ask from reviewer on PR #2400 comment #4567890",
+         "parent_comment_id": "4567890"
+       }
+     ]
+   }
+   ```
+   `engine/lifecycle.js processCompletionFollowups` logs each entry at `info`
+   and warns if the claimed `wi_id` is missing from any project's
+   `work-items.json` (catches reverted or non-landing dispatches).
+
+## Server contract reference
+
+**Headers** (`dashboard.js handleWorkItemsCreate`):
+
+| Header | Type | Persisted as | Notes |
+|---|---|---|---|
+| `X-Minions-Agent` | `^[A-Za-z0-9._:-]{1,128}$` | `_originAgent` | Agent id (`lambert`, `temp-…`). Both headers are optional but recommended for traceability. |
+| `X-Minions-Origin-Wi` | `^[A-Za-z0-9._:-]{1,128}$` | `_originWi` | The dispatch's parent WI id. |
+
+**`meta.pr_followup` shape** (validated by `validatePrFollowupShape` in
+`dashboard.js`):
+
+```ts
+{
+  parent_pr_url: string,        // required, ≤ 512 chars
+  parent_pr_id:  string,        // required, ≤ 512 chars (canonical id, e.g. github:owner/repo#123 or PR-123)
+  parent_comment_id: string,    // required, ≤ 512 chars (host comment/thread id; key for dedup)
+  parent_comment_author: string // required, ≤ 512 chars
+}
+```
+
+Any missing/empty field, oversized field, or non-string value → `400` with a
+descriptive message.
+
+**Dedup.** A second `POST /api/work-items` with the same
+`meta.pr_followup.parent_comment_id` in the same project's `work-items.json`
+returns `409 { error: "followup_already_dispatched", existingWiId: "<id>" }`.
+This is checked under the same `mutateWorkItems` lock used to insert the new
+WI, so two pollers racing on the same comment cannot both win.
+
+Treat 409 as a **success** for the agent's purposes — the follow-up already
+exists; you still reply on the comment thread with the returned id.
+
+## What does NOT change
+
+- The pollers (`engine/github.js`, `engine/ado.js`) still set
+  `pr.humanFeedback.pendingFix:true` for every actionable human comment.
+- `discover-from-prs` still queues `fix` dispatches against the original
+  branch; nothing prevents the in-place fix from proceeding.
+- Follow-up routing is not auto-pinned to any agent — `routing.md` resolves
+  the new WI to the appropriate agent based on `type` + `project`.
+- The follow-up is **descriptive** in the completion report: the engine does
+  not auto-create the WI from the report. Creation happens when the agent
+  calls the API; the `followups` array is the auditable record.
+
+## When to use this carve-out (and when not)
+
+**Use it when:**
+
+- The reviewer explicitly asks to "track separately", "do in a follow-up", or
+  "open a new PR".
+- The ask is in a different file/system/feature area than the current diff.
+- Adding the change to this PR would more than double the review surface.
+
+**Do NOT use it for:**
+
+- Nits, style notes, or things you were already going to do in this PR.
+- Asks that block correctness of the current PR (those are the original
+  "fix it" path).
+- Asks that are invalid, stale, or harmful (those are the "rebut with
+  rationale" path — no follow-up).
+
+## Where the wiring lives
+
+| File | Role |
+|---|---|
+| `playbooks/templates/followup-dispatch.md` | Canonical decision tree + curl shape + dedup contract. Referenced from `fix.md` and `review.md`. |
+| `playbooks/fix.md` (`## Follow-up Dispatch`) | Carve-out for fix agents; updated decision tree splitting "fix it / rebut it / spin off". |
+| `playbooks/review.md` (`## Follow-up Dispatch`) | Same carve-out for review agents who spot trackable out-of-scope work. |
+| `playbooks/shared-rules.md` (`## Minions API access`) | Documents the dashboard URL, the route registry endpoint, and the `X-Minions-Agent` / `X-Minions-Origin-Wi` headers. |
+| `dashboard.js` (`validatePrFollowupShape`, `findExistingFollowupForComment`, `extractMinionsAgentHeader`, `extractMinionsOriginWiHeader`, `handleWorkItemsCreate`) | Shape validation, parent_comment_id dedup, header persistence, 200/400/409 responses. |
+| `dashboard/js/render-work-items.js` (`prFollowup` block in `wiRow`) | `↪ from PR #N` chip on follow-up WIs. |
+| `dashboard/js/render-prs.js` (`_countPrFollowups`) | `+N follow-ups` chip on PR rows. |
+| `engine/lifecycle.js` (`processCompletionFollowups`) | Parses the optional `followups` array on completion reports; warns on mismatch. |
+| `docs/completion-reports.md` (`PR-comment follow-ups`) | Schema for the optional `followups` array. |
+
+## Migration / rollout
+
+This is purely additive. Existing fix/review playbooks continue to work
+without setting `meta.pr_followup`; the validator runs only when the field is
+present. Agents that don't know about the carve-out keep doing in-place fixes
+and rebuttals exactly as before.
+
+To adopt:
+
+1. Update agent prompts (already done in this PR via `playbooks/fix.md` and
+   `playbooks/review.md`).
+2. Agents read the contract in `playbooks/templates/followup-dispatch.md`
+   when they reach the `## Follow-up Dispatch` section of their playbook.
+3. The next time a reviewer asks for an out-of-scope follow-up, the fix
+   agent fans out a new WI instead of refusing or broadening the PR.
+
+## Related
+
+- `engine/github.js pollPrHumanComments` (human-comment routing — unchanged)
+- `engine.js HUMAN_FEEDBACK fix dispatch` (in-place fix flow — unchanged)
+- `playbooks/templates/followup-dispatch.md` (the contract agents read)
+- `docs/completion-reports.md` `PR-comment follow-ups` section

package/engine/lifecycle.js

@@ -3360,6 +3360,74 @@ function extractDecompositionJson(stdout, runtimeName) {
   return null;
 }
 
+/**
+ * PR follow-up audit (W-mpej3cox00099466).
+ *
+ * Parses the optional `followups` array on the agent's completion report,
+ * logs each entry at `info` so operators can trace fan-out, and warns when
+ * a claimed `wi_id` doesn't match any record in central or per-project
+ * work-items.json. The mismatch warning catches dispatches that were reverted
+ * (HTTP 409 from /api/work-items dedup), fingerprinted away by the standard
+ * dedup window, or otherwise didn't actually land — situations where the
+ * agent claimed a follow-up exists but the dashboard/engine has no record.
+ *
+ * Returns the array of well-formed followup entries; malformed entries (non-
+ * object, missing `wi_id`) are logged and skipped. Failures inside the
+ * existence check are non-fatal — they degrade to a warn.
+ */
+function processCompletionFollowups(completion, agentId, dispatchItem, config) {
+  if (!completion || typeof completion !== 'object') return [];
+  const raw = completion.followups;
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    log('warn', `Followup audit: completion.followups must be an array; got ${typeof raw}`);
+    return [];
+  }
+  if (raw.length === 0) return [];
+  const wiId = dispatchItem?.meta?.item?.id || 'N/A';
+  let existingIds = null;
+  function loadExistingIds() {
+    if (existingIds !== null) return existingIds;
+    try {
+      existingIds = new Set(queries.getWorkItems(config).map(w => w && w.id).filter(Boolean));
+    } catch (err) {
+      log('warn', `Followup audit: getWorkItems failed (${err.message}); skipping existence checks`);
+      existingIds = new Set();
+    }
+    return existingIds;
+  }
+  const accepted = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') {
+      log('warn', `Followup audit (${agentId || 'unknown'} wi=${wiId}): skipping malformed entry (not an object)`);
+      continue;
+    }
+    const followupWiId = typeof entry.wi_id === 'string' ? entry.wi_id.trim()
+      : (typeof entry.wiId === 'string' ? entry.wiId.trim() : '');
+    if (!followupWiId) {
+      log('warn', `Followup audit (${agentId || 'unknown'} wi=${wiId}): skipping entry without wi_id`);
+      continue;
+    }
+    const title = typeof entry.title === 'string' ? entry.title.trim() : '';
+    const reason = typeof entry.reason === 'string' ? entry.reason.trim() : '';
+    const parentCommentId = typeof entry.parent_comment_id === 'string'
+      ? entry.parent_comment_id.trim()
+      : (typeof entry.parentCommentId === 'string' ? entry.parentCommentId.trim() : '');
+    log('info', `Followup audit (${agentId || 'unknown'} wi=${wiId}): dispatched ${followupWiId}${title ? ` — ${title}` : ''}${parentCommentId ? ` (comment=${parentCommentId})` : ''}${reason ? ` — ${reason}` : ''}`);
+    const allIds = loadExistingIds();
+    if (allIds.size > 0 && !allIds.has(followupWiId)) {
+      log('warn', `Followup audit (${agentId || 'unknown'} wi=${wiId}): claimed followup ${followupWiId} not found in any work-items.json — dispatch may have been deduped, reverted, or never landed`);
+    }
+    accepted.push({
+      wi_id: followupWiId,
+      title,
+      reason,
+      parent_comment_id: parentCommentId,
+    });
+  }
+  return accepted;
+}
+
 /**
  * Handle decomposition result — parse sub-items from agent output and create child work items.
  * Called from runPostCompletionHooks when type === 'decompose'.
@@ -3538,6 +3606,17 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     if (structuredCompletion.summary) resultSummary = String(structuredCompletion.summary);
     log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}${structuredCompletion._source ? ` (${structuredCompletion._source})` : ''}`);
   }
+  // PR follow-up audit (W-mpej3cox00099466) — when the agent declares
+  // `followups: [{wi_id, title, reason, parent_comment_id}]` in its completion
+  // report, log each entry and verify the claimed WI ids actually landed in
+  // some project's work-items.json. A mismatch (claimed wi_id with no matching
+  // record) is logged at warn so operators can spot dispatches that were
+  // reverted, fingerprinted-deduped, or otherwise didn't take.
+  if (structuredCompletion) {
+    try {
+      processCompletionFollowups(structuredCompletion, agentId, dispatchItem, config);
+    } catch (err) { log('warn', `Followup audit: ${err.message}`); }
+  }
   // F5 (W-mpeklod3000we69c): if the agent flagged an injection attempt in the
   // structured completion, force the dispatch into a non-retryable failure
   // with `FAILURE_CLASS.INJECTION_FLAGGED`. Inbox note + WI stamp are written
@@ -4303,4 +4382,5 @@ module.exports = {
   isPrAttachmentRequired,
   extractDecompositionJson,
   handleDecompositionResult,
+  processCompletionFollowups,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1999",
+  "version": "0.1.2000",
   "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

@@ -35,6 +35,7 @@ Before editing, split the feedback into:
 
 - **Blocking findings to fix:** verified correctness, safety, build/test failure, missing requested behavior, broken compatibility, or approval-blocking comments whose claim is valid on the current branch.
 - **Findings to answer with rationale:** comments where the current approach is intentionally correct, the reviewer misunderstood the code, the issue is stale/already addressed, or the requested change would broaden the PR beyond its purpose.
+- **Out-of-scope but legitimate follow-up requests:** asks for genuinely useful work that does **not** belong in this PR (a separate bug, a related-but-distinct feature, a refactor the reviewer explicitly said to "track separately"). Spin off a new Minions work item — see `## Follow-up Dispatch` below — and reply on the originating thread with the new WI id. This is a third option alongside "fix it" and "rebut it"; it does **not** loosen the don't-broaden-the-PR rule for in-PR work.
 - **Non-blocking suggestions:** style, optional refactors, extra docs, or enhancements that are not required for approval. Do not implement these unless they are necessary to resolve a verified blocking issue.
 
 ## Health Check
@@ -55,7 +56,7 @@ Handle this like the PR author responding directly from a CLI:
   - Fix it if the feedback is valid and improves correctness, safety, maintainability, or test coverage.
   - If the current approach is intentionally correct, stale, already fixed, out of scope, or the requested change would be harmful, reply with specific rationale instead of silently changing code or ignoring the thread.
 - Handle merge conflicts when needed, preserving the PR's intended changes while keeping the branch reviewable.
-- Do not add unrelated cleanups or broaden the PR beyond the review feedback unless that is necessary to make the fix correct.
+- Do not add unrelated cleanups or broaden the PR beyond the review feedback unless that is necessary to make the fix correct. For legitimate-but-out-of-scope asks, see `## Follow-up Dispatch` below — spin off a separate WI instead of broadening this PR.
 
 ## Validation
 
@@ -94,6 +95,20 @@ After pushing, respond to each review comment/thread:
 - **GitHub**: Reply to each review comment, resolve conversations you've fixed
 - **ADO**: Use `az` CLI first to reply to each thread and update status when supported; use ADO MCP only as a fallback when `az` is unavailable or insufficient. Set status to `fixed` or `closed` for fixes; leave `active` for rationale replies
 
+## Follow-up Dispatch
+
+When a comment asks for legitimate work that is **clearly out of scope** for this PR (separate bug, different feature, refactor the reviewer explicitly asked to "track separately"), spin off a new Minions work item via the dashboard API instead of broadening the PR or silently declining. Read the full contract — decision tree, exact curl shape, required `meta.pr_followup` fields, dedup behavior, and the mandatory comment-thread reply — at:
+
+`{{team_root}}/playbooks/templates/followup-dispatch.md`
+
+Key rules (full detail in the template):
+
+- The follow-up is **additive**. You still fix the in-scope feedback in this PR and post the normal fix comment.
+- Reply on the originating comment thread with the new WI id (e.g. `Tracked as follow-up: W-…`) and resolve that sub-thread.
+- Always include `meta.pr_followup.parent_comment_id` — without it the server cannot dedup retries.
+- Do not pick `agent`; let `routing.md` decide.
+- Record every follow-up you dispatched in the `followups` array of your completion JSON.
+
 ## When to Stop
 
 Your task is complete when each review finding has either been fixed or answered with rationale, the validation story is truthful and sufficient for review, the fix is pushed if code changed, the PR is commented, and addressed threads are resolved. Do NOT continue into unrelated improvements.

package/playbooks/review.md

@@ -98,6 +98,20 @@ After running the command, confirm it succeeded (check the command output for er
 If you encounter merge conflicts (e.g., the PR shows conflicts):
 1. Note the conflict in your review comment. Do NOT attempt to resolve — flag it for the author.
 
+## Follow-up Dispatch
+
+If, while reviewing, you spot substantial work that should be tracked separately rather than blocking this PR (a related-but-distinct bug, a feature gap that didn't ship in this diff, a refactor that's worth doing later), you may dispatch a follow-up Minions work item instead of pinning it as a blocking finding. Read the full contract — decision tree, exact curl shape, required `meta.pr_followup` fields, dedup behavior, and the mandatory comment-thread reply — at:
+
+`{{team_root}}/playbooks/templates/followup-dispatch.md`
+
+Key rules (full detail in the template):
+
+- Use this for **legitimate out-of-scope follow-ups**, not for findings that should block the PR.
+- The review verdict (`APPROVE` / `REQUEST_CHANGES`) is unchanged by the follow-up — pick the verdict based on the PR's own contents.
+- Reply on the originating thread with the new WI id and resolve that sub-thread (do not leave it open).
+- Always include `meta.pr_followup.parent_comment_id` so the server can dedup if you (or another agent) retries.
+- Record every follow-up you dispatched in the `followups` array of your completion JSON.
+
 ## Do not run git checkout on the main working tree. Use `git diff` and `git show` only.
 
 ## When to Stop

package/playbooks/shared-rules.md

@@ -92,6 +92,27 @@ The engine provides a completion report path in the prompt and in `MINIONS_COMPL
 
 For the canonical schema — every field, the `failure_class` enum, `noop:true` semantics, `retryable` / `needs_rerun` shape, and the artifacts array — see `docs/completion-reports.md`. The JSON report is the primary signal; fenced `completion` blocks in stdout are accepted only as a fallback.
 
+## Minions API access
+
+The Minions dashboard runs at `http://localhost:7331` whenever the engine is up. Agents may call its HTTP endpoints when (and only when) the playbook explicitly authorizes it for a particular task — most dispatches do not need any API access, and uninvited writes to engine-managed state are still prohibited (see "Do NOT write to `agents/*/status.json`" above).
+
+When a playbook authorizes an API call (e.g. follow-up work-item dispatch from `playbooks/templates/followup-dispatch.md`), use the standard `curl` shape:
+
+```bash
+curl -sS -X POST http://localhost:7331/api/<route> \
+  -H 'Content-Type: application/json' \
+  -H 'X-Minions-Agent: <your-agent-id>' \
+  -H 'X-Minions-Origin-Wi: <current-work-item-id>' \
+  -d '<json-payload>'
+```
+
+Conventions:
+
+- The full live route surface is available at `GET http://localhost:7331/api/routes` (the route registry includes method, path, and a one-line description for every handler).
+- **Identification headers (for traceability, not auth).** Set `X-Minions-Agent` to your agent id and `X-Minions-Origin-Wi` to the work-item id you were dispatched against. Endpoints that persist these (e.g. `POST /api/work-items`) store them as `_originAgent` / `_originWi` for the dashboard timeline. Agents do **not** have a `X-CC-Turn-Id` — that header is reserved for Command Center turns.
+- The dashboard binds to `127.0.0.1` only; no auth token is required for localhost calls.
+- Treat HTTP 4xx as a contract violation: surface the response body in your completion summary instead of retrying blindly.
+
 ## Long-Running Commands
 
 Builds, dependency installs, tests, and local servers can be quiet for long periods. Run the repo's normal CLI commands and let them finish; do not add artificial progress output, heartbeat loops, or command-specific workarounds just to keep Minions active.

package/playbooks/templates/followup-dispatch.md

@@ -0,0 +1,157 @@
+# Follow-up Dispatch (PR-comment → new WI)
+
+When a human leaves a PR comment that asks for work that is **legitimate but
+outside the scope of the current PR** (a different bug, a related-but-separate
+feature, a follow-up cleanup that doesn't belong in the current diff), do **not**
+broaden the PR and do **not** silently rebut the comment. Spin off a new Minions
+work item via the dashboard API and reply on the originating comment thread with
+a link to it.
+
+This carve-out only enables creating a **separate** work item. It does not
+loosen the rule that the *current* PR should stay focused on the original
+review feedback.
+
+## Decision tree
+
+For each human comment that asks for additional work, classify it before
+editing:
+
+1. **Fix in this PR** — the request is in scope (regression of the current
+   diff, a flaw in the new code, missing requested behavior the PR was already
+   supposed to cover). Fix it on this branch, push, reply on the thread.
+2. **Answer with rationale** — the request is invalid, stale, already
+   addressed, or would harm the code. Post an evidence-backed rebuttal on the
+   thread; do **not** create a follow-up WI for it.
+3. **Follow-up WI** — the request is legitimate but clearly out of scope for
+   the current PR (different file/system, different bug, distinct feature, a
+   refactor the reviewer explicitly asked you to "track separately" or "do in a
+   follow-up"). Create a new work item via the API (see below) and reply on the
+   originating thread with the new WI id.
+
+If you are unsure between #1 and #3, prefer **#3 (follow-up)** so the current
+PR stays small and reviewable. If you are unsure between #2 and #3, prefer #2
+and explain your reasoning — don't manufacture work.
+
+## The API call
+
+The Minions dashboard runs on `http://localhost:7331`. Create a follow-up work
+item with `POST /api/work-items`:
+
+```bash
+curl -sS -X POST http://localhost:7331/api/work-items \
+  -H 'Content-Type: application/json' \
+  -H 'X-Minions-Agent: <your-agent-id>' \
+  -H 'X-Minions-Origin-Wi: <current-wi-id>' \
+  -d '{
+    "title": "Short imperative summary of the follow-up",
+    "type": "implement",
+    "priority": "medium",
+    "project": "<project-name>",
+    "description": "Why this is a follow-up, what should change, acceptance.\n\nOriginated from <reviewer> on PR #<N> (<url>): \"<verbatim quote of the ask>\"",
+    "references": [
+      {"url": "<originating-pr-url>", "label": "Originated from PR #<N> comment"}
+    ],
+    "meta": {
+      "pr_followup": {
+        "parent_pr_url": "<originating-pr-url>",
+        "parent_pr_id":  "<canonical PR id, e.g. github:owner/repo#123 or PR-123>",
+        "parent_comment_id": "<exact comment/thread id from the host API>",
+        "parent_comment_author": "<reviewer login>"
+      }
+    }
+  }'
+```
+
+Required fields and their conventions:
+
+- **`title`** — short imperative ("Add foo to bar", "Fix off-by-one in baz").
+- **`type`** — pick from the routing types (`implement`, `fix`, `test`,
+  `docs`, `ask`, `explore`, …). For new feature/fix work, `implement` is
+  almost always correct; use `fix` only when the follow-up is about an existing
+  PR's bug. Do **not** set `agent` — let `routing.md` pick.
+- **`project`** — name of the same project the originating PR belongs to.
+  Required when more than one project is configured.
+- **`description`** — explain *why* this is a follow-up and quote the exact
+  ask. Future readers should understand the scope without re-reading the PR
+  thread.
+- **`references`** — at least one entry pointing back at the originating PR.
+- **`meta.pr_followup`** — the four-field shape above. Used by the dashboard
+  for traceability chips and by the server for dedup (a second request with the
+  same `parent_comment_id` returns the existing WI id rather than creating a
+  duplicate).
+
+Headers:
+
+- **`X-Minions-Agent`** — your agent id (e.g. `lambert`, `ripley`,
+  `temp-mp3dop1v…`). Persisted as `_originAgent` on the new WI.
+- **`X-Minions-Origin-Wi`** — the id of the work item you were dispatched
+  against (the one whose PR you are responding to). Persisted as `_originWi`.
+
+Both headers are optional but strongly recommended — they let the dashboard
+correlate the follow-up to the dispatch that created it.
+
+## Server responses
+
+| Status | Body | Meaning |
+|---|---|---|
+| 200 | `{ ok: true, id: "W-…" }` | New follow-up WI created. |
+| 200 | `{ ok: true, id: "W-…", duplicate: true, duplicateOf: "W-…" }` | The standard title/type/project dedup window matched an in-flight WI. Same WI id is returned; reply on the comment thread with that id. |
+| 409 | `{ error: "followup_already_dispatched", existingWiId: "W-…" }` | Another agent (or your previous attempt) already dispatched a follow-up for this exact `parent_comment_id`. Reply on the comment thread linking the existing WI; do not retry. |
+| 400 | `{ error: "<message>" }` | Validation failed. Inspect the message: the most common cause is a malformed `meta.pr_followup` shape. Fix and retry. |
+
+Treat 409 as a **success** for your purposes — the follow-up exists, you just
+weren't the one who created it. Still post the reply on the comment thread with
+the returned `existingWiId`.
+
+## Mandatory post-dispatch step
+
+After the API call returns a WI id (whether `id` from 200 or `existingWiId`
+from 409), reply on the originating comment thread with a link back:
+
+> Tracked as follow-up: **W-…** — see the Minions dashboard. Continuing with
+> the in-place fix on this PR.
+
+Then **resolve that sub-thread** (GitHub: "Resolve conversation"; ADO: set
+status to `closed`) even if other review threads on the PR are still open. The
+follow-up WI is the durable artifact; the comment thread should not be left
+hanging.
+
+## Record the follow-up in your completion report
+
+Add a `followups` array to your JSON completion report so the engine has an
+auditable record of what you fanned out to:
+
+```json
+{
+  "status": "success",
+  "summary": "…",
+  "followups": [
+    {
+      "wi_id": "W-mp7abc…",
+      "title": "Add foo to bar",
+      "reason": "Out-of-scope ask from reviewer on PR #123 comment #4567890",
+      "parent_comment_id": "4567890"
+    }
+  ]
+}
+```
+
+The engine logs each entry at `info` and warns if the array references a WI id
+that doesn't exist in any project's `work-items.json` (mismatch between what
+you claim and what the API actually created — usually a sign that the dispatch
+was reverted or the response was misread).
+
+## Do NOT
+
+- Do not pick `agent` for the follow-up; the routing layer assigns one based
+  on `type` + `project`.
+- Do not set `X-CC-Turn-Id` (that header is for Command Center turns; agents
+  don't have a turn id). Use `X-Minions-Agent`/`X-Minions-Origin-Wi` instead.
+- Do not skip the comment-thread reply — without it, the human has no signal
+  that their ask was tracked and the engine will keep re-routing the comment
+  as `pendingFix`.
+- Do not spin off follow-ups for nits, style notes, or things you are about
+  to fix in this PR anyway. Reserve this for asks that genuinely belong in a
+  separate WI.
+- Do not omit `meta.pr_followup.parent_comment_id`; without it the server
+  cannot dedup and you will create duplicates on every retry.