@yemi33/minions 0.1.1998 → 0.1.2000

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.1998",
+  "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.