@yemi33/minions 0.1.1998 → 0.1.2000

package/dashboard/pages/qa.html

@@ -1,11 +1,58 @@
       <section>
         <h2>QA</h2>
-        <p class="empty" style="margin:4px 0 12px 0">Canonical home for human-driven and agent-driven validation against running managed instances. Runbook dispatch lands in a follow-up WI.</p>
+        <p class="empty" style="margin:4px 0 12px 0">Validation runbooks dispatched against live managed instances. Targets, runbooks, and run history with artifact previews.</p>
       </section>
-      <section id="qa-runbooks-section">
-        <h2>Validation Runbooks <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">human or agent-driven smoke / E2E flows against the live instances above</span></h2>
-        <div style="border:1px dashed var(--border);border-radius:6px;padding:16px;background:var(--surface2);text-align:center">
-          <p class="empty" style="margin:0 0 12px 0">Validation runbooks will live here. Coming soon: dispatch a human or agent to validate a running instance.</p>
-          <button id="qa-new-runbook-btn" disabled title="Coming soon — runbook schema lands in the next WI" style="padding:6px 14px;background:var(--surface);color:var(--muted);border:1px solid var(--border);border-radius:4px;cursor:not-allowed;font-size:12px">+ New runbook</button>
+      <section id="qa-targets-section" class="qa-section">
+        <h2>Targets <span class="qa-section-subtitle">live managed/keep processes available as runbook targets — full inventory lives on <a href="/engine" class="qa-engine-link">/engine</a></span></h2>
+        <div id="qa-targets-content" class="qa-targets-list">
+          <p class="empty">Loading targets…</p>
+        </div>
+      </section>
+      <section id="qa-runbooks-section" class="qa-section">
+        <h2>Validation Runbooks <span class="qa-section-subtitle">human or agent-driven smoke / E2E flows against the targets above</span></h2>
+        <div class="qa-runbooks-actions">
+          <button id="qa-new-runbook-btn" class="qa-btn-primary" onclick="qaShowNewRunbookForm()">+ New runbook</button>
+        </div>
+        <div id="qa-runbook-form-wrap" class="qa-runbook-form" style="display:none">
+          <form id="qa-runbook-form" onsubmit="event.preventDefault();qaSaveRunbook();">
+            <div class="qa-form-row">
+              <label class="qa-form-label" for="qa-runbook-name">Name</label>
+              <input id="qa-runbook-name" type="text" class="qa-form-input" placeholder="login-smoke" required>
+            </div>
+            <div class="qa-form-row">
+              <label class="qa-form-label" for="qa-runbook-target">Target</label>
+              <select id="qa-runbook-target" class="qa-form-input" required>
+                <option value="">— select a target —</option>
+              </select>
+            </div>
+            <div class="qa-form-row">
+              <label class="qa-form-label" for="qa-runbook-steps">Steps</label>
+              <textarea id="qa-runbook-steps" class="qa-form-input qa-form-textarea" placeholder="1. Open the app&#10;2. Click login&#10;3. Verify dashboard loads" required></textarea>
+            </div>
+            <div class="qa-form-row">
+              <label class="qa-form-label">Expected artifacts</label>
+              <div id="qa-runbook-artifacts" class="qa-artifacts-repeater">
+                <div class="qa-artifact-row">
+                  <input type="text" class="qa-form-input qa-artifact-input" placeholder="screenshot:dashboard.png">
+                  <button type="button" class="qa-btn-ghost" onclick="qaRemoveArtifactRow(this)">−</button>
+                </div>
+              </div>
+              <button type="button" class="qa-btn-ghost qa-add-artifact-btn" onclick="qaAddArtifactRow()">+ Add artifact</button>
+            </div>
+            <div class="qa-form-row qa-form-actions">
+              <button type="submit" class="qa-btn-primary">Save</button>
+              <button type="button" class="qa-btn-ghost" onclick="qaHideNewRunbookForm()">Cancel</button>
+              <span id="qa-runbook-form-msg" class="qa-form-msg"></span>
+            </div>
+          </form>
+        </div>
+        <div id="qa-runbooks-content" class="qa-runbooks-list">
+          <p class="empty">Loading runbooks…</p>
+        </div>
+      </section>
+      <section id="qa-runs-section" class="qa-section">
+        <h2>Recent Runs <span class="qa-section-subtitle">latest 50 dispatched validation runs — polled every 5s while this page is active</span></h2>
+        <div id="qa-runs-content" class="qa-runs-list">
+          <p class="empty">Loading runs…</p>
         </div>
       </section>

package/dashboard/styles.css

@@ -736,3 +736,152 @@
     display: inline-block; max-width: 240px; overflow: hidden;
     text-overflow: ellipsis; white-space: nowrap; vertical-align: bottom;
   }
+
+  /* QA tab (W-mpeiwz6k0005bf34-d) — targets / runbooks / runs sections.
+   * Reuses surface/border/text tokens defined in :root so the QA page
+   * blends with the rest of the dashboard. */
+  .qa-section { padding: var(--space-7) var(--space-9); }
+  .qa-section h2 { display: flex; align-items: baseline; gap: var(--space-4); }
+  .qa-section-subtitle {
+    font-size: var(--text-sm); color: var(--muted);
+    font-weight: 400; text-transform: none; letter-spacing: 0;
+  }
+  .qa-engine-link { color: var(--blue); text-decoration: none; }
+  .qa-engine-link:hover { text-decoration: underline; }
+
+  /* Targets list — slim row per dedup'd target. */
+  .qa-targets-list {
+    display: flex; flex-direction: column; gap: var(--space-2);
+    border: 1px solid var(--border); border-radius: var(--radius-md);
+    background: var(--surface2); padding: var(--space-4);
+  }
+  .qa-target-row {
+    display: flex; align-items: center; gap: var(--space-5);
+    padding: var(--space-3) var(--space-4);
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--radius-sm); font-size: var(--text-md);
+  }
+  .qa-target-main { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+  .qa-target-name { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-weight: 600; color: var(--text); }
+  .qa-target-project { color: var(--muted); font-size: var(--text-base); }
+  .qa-target-source {
+    display: inline-block; margin-left: var(--space-3);
+    font-size: var(--text-xs); color: var(--muted);
+    border: 1px solid var(--border); border-radius: var(--radius-sm);
+    padding: 1px var(--space-3); text-transform: uppercase;
+  }
+  .qa-target-meta { font-size: var(--text-base); color: var(--muted); white-space: nowrap; }
+  .qa-target-link {
+    font-size: var(--text-sm); color: var(--blue); text-decoration: none;
+    padding: var(--space-1) var(--space-4); border: 1px solid var(--border);
+    border-radius: var(--radius-sm); background: var(--surface2);
+  }
+  .qa-target-link:hover { background: var(--bg); }
+  .qa-health-dot { font-size: var(--text-md); }
+  .qa-health-ok { color: var(--green); }
+  .qa-health-warn { color: var(--yellow); }
+  .qa-health-down { color: var(--muted); }
+
+  /* Runbooks list + inline new-runbook form. */
+  .qa-runbooks-actions { margin-bottom: var(--space-5); }
+  .qa-runbook-form {
+    border: 1px solid var(--border); border-radius: var(--radius-md);
+    background: var(--surface2); padding: var(--space-5);
+    margin-bottom: var(--space-5);
+  }
+  .qa-form-row { display: flex; flex-direction: column; gap: var(--space-2); margin-bottom: var(--space-5); }
+  .qa-form-label { font-size: var(--text-base); color: var(--muted); font-weight: 600; }
+  .qa-form-input {
+    background: var(--bg); color: var(--text);
+    border: 1px solid var(--border); border-radius: var(--radius-sm);
+    padding: var(--space-3) var(--space-4); font-size: var(--text-md);
+    font-family: inherit;
+  }
+  .qa-form-input:focus { border-color: var(--blue); outline: none; }
+  .qa-form-textarea { min-height: 88px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; resize: vertical; }
+  .qa-artifacts-repeater { display: flex; flex-direction: column; gap: var(--space-2); }
+  .qa-artifact-row { display: flex; gap: var(--space-3); align-items: center; }
+  .qa-artifact-input { flex: 1; }
+  .qa-add-artifact-btn { align-self: flex-start; margin-top: var(--space-2); }
+  .qa-form-actions { flex-direction: row; align-items: center; gap: var(--space-4); }
+  .qa-form-msg { font-size: var(--text-base); margin-left: var(--space-3); }
+  .qa-btn-primary {
+    background: var(--blue); color: #fff; border: none;
+    border-radius: var(--radius-sm); padding: var(--space-3) var(--space-7);
+    font-size: var(--text-md); font-weight: 600; cursor: pointer;
+  }
+  .qa-btn-primary:hover { opacity: 0.9; }
+  .qa-btn-primary:disabled { opacity: 0.4; cursor: not-allowed; }
+  .qa-btn-ghost {
+    background: transparent; color: var(--muted);
+    border: 1px solid var(--border); border-radius: var(--radius-sm);
+    padding: var(--space-2) var(--space-5); font-size: var(--text-base);
+    cursor: pointer;
+  }
+  .qa-btn-ghost:hover { color: var(--text); background: var(--surface); }
+
+  .qa-runbooks-list { display: flex; flex-direction: column; gap: var(--space-3); }
+  .qa-runbook-row {
+    display: flex; align-items: center; gap: var(--space-5);
+    padding: var(--space-4) var(--space-5);
+    background: var(--surface2); border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+  }
+  .qa-runbook-main { flex: 1; min-width: 0; }
+  .qa-runbook-name { font-weight: 600; color: var(--text); font-size: var(--text-md); }
+  .qa-runbook-meta { font-size: var(--text-base); color: var(--muted); margin-top: var(--space-1); }
+
+  /* Runs list — status badge + inline artifact previews. */
+  .qa-runs-list { display: flex; flex-direction: column; gap: var(--space-4); }
+  .qa-run-row {
+    border: 1px solid var(--border); border-radius: var(--radius-md);
+    background: var(--surface2); padding: var(--space-4) var(--space-5);
+  }
+  .qa-run-head { display: flex; align-items: center; gap: var(--space-4); flex-wrap: wrap; font-size: var(--text-md); }
+  .qa-run-status {
+    display: inline-block; font-size: var(--text-xs); font-weight: 700;
+    padding: 2px var(--space-3); border-radius: var(--radius-sm);
+    text-transform: uppercase; letter-spacing: 0.5px;
+    background: var(--surface); color: var(--muted); border: 1px solid var(--border);
+  }
+  .qa-status-passed, .qa-status-success { color: var(--green); border-color: var(--green); }
+  .qa-status-failed, .qa-status-error { color: var(--red); border-color: var(--red); }
+  .qa-status-running, .qa-status-dispatched { color: var(--blue); border-color: var(--blue); }
+  .qa-status-pending { color: var(--yellow); border-color: var(--yellow); }
+  .qa-run-name { font-weight: 600; color: var(--text); }
+  .qa-run-target { color: var(--muted); font-size: var(--text-base); }
+  .qa-run-ts { color: var(--muted); font-size: var(--text-base); margin-left: auto; }
+  .qa-run-actions { margin-left: var(--space-5); }
+  .qa-run-link { color: var(--blue); text-decoration: none; font-size: var(--text-base); }
+  .qa-run-link:hover { text-decoration: underline; }
+
+  .qa-run-artifacts {
+    display: flex; flex-wrap: wrap; gap: var(--space-4);
+    margin-top: var(--space-4); padding-top: var(--space-4);
+    border-top: 1px solid var(--border);
+  }
+  .qa-artifact {
+    display: flex; flex-direction: column; gap: var(--space-2);
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--radius-sm); padding: var(--space-3);
+    max-width: 320px;
+  }
+  .qa-artifact img, .qa-artifact video {
+    max-width: 100%; max-height: 200px; border-radius: var(--radius-sm);
+    background: var(--bg);
+  }
+  .qa-artifact-caption {
+    font-size: var(--text-xs); color: var(--muted);
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    word-break: break-all;
+  }
+  .qa-artifact-fulllink { color: var(--blue); text-decoration: none; margin-left: var(--space-3); }
+  .qa-artifact-fulllink:hover { text-decoration: underline; }
+  .qa-artifact-log-preview {
+    background: var(--bg); color: var(--text);
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: var(--text-xs); padding: var(--space-3);
+    border-radius: var(--radius-sm); margin: 0;
+    max-height: 160px; overflow: auto; white-space: pre;
+  }
+  .qa-artifact-log { max-width: 480px; }

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