@mmerterden/multi-agent-pipeline 17.5.1 → 17.6.0

package/pipeline/schemas/agent-state.schema.json

@@ -97,7 +97,9 @@
           "enum": ["remote", "local"],
           "description": "Where the candidate ref list came from. local means the fetch failed and the list is the local cache plus local heads - possibly stale, possibly incomplete."
         },
-        "chosen": { "type": "string" },
+        "chosen": {
+          "type": "string"
+        },
         "ambiguous": {
           "type": "boolean",
           "description": "Two or more candidates tied at the top score. Autopilot may not record derived when this is true."
@@ -107,8 +109,13 @@
           "additionalProperties": false,
           "description": "The release-branch template inferred from the refs that exist, never from a built-in table.",
           "properties": {
-            "template": { "type": "string" },
-            "members": { "type": "integer", "minimum": 0 }
+            "template": {
+              "type": "string"
+            },
+            "members": {
+              "type": "integer",
+              "minimum": 0
+            }
           }
         },
         "candidates": {
@@ -118,9 +125,18 @@
             "additionalProperties": false,
             "required": ["branch"],
             "properties": {
-              "branch": { "type": "string" },
-              "score": { "type": "number" },
-              "refs": { "type": "array", "items": { "type": "string" } },
+              "branch": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              },
+              "refs": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
               "evidence": {
                 "type": "array",
                 "items": {
@@ -140,26 +156,121 @@
                         "ref-provenance"
                       ]
                     },
-                    "detail": { "type": "string" }
+                    "detail": {
+                      "type": "string"
+                    }
                   }
                 }
               }
             }
           }
         },
-        "notes": { "type": "array", "items": { "type": "string" } },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "askedOnIssue": {
           "type": ["object", "null"],
           "additionalProperties": false,
           "description": "The one comment autopilot is allowed to post when the derivation is ambiguous, gated by prefs.global.baseBranchEvidence.autopilotAsksOnIssue (default false). A question, never a state change: no transition, no close, no assignee. Posting it trips circuit-breaker trigger 6 and the run waits for resume.",
           "properties": {
-            "target": { "type": "string" },
-            "url": { "type": "string" },
-            "at": { "type": "string", "format": "date-time" }
+            "target": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            },
+            "at": {
+              "type": "string",
+              "format": "date-time"
+            }
           }
         }
       }
     },
+    "maturity": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How ready the fetched item was to be developed. Produced by lib/issue-fetcher.sh, which owns the gap codes and their localized wording. Declared as of v17.6.0 - it had been written by every issue-shaped run since long before and read by Phase 0, Phase 4 and the clarifier, while this schema forbade it under additionalProperties: false.",
+      "properties": {
+        "score": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "maximum": 100,
+          "description": "100 minus 40 per blocker and 10 per warning. Null for free-text input: there is no item to be immature."
+        },
+        "blockers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Stable gap codes that stop a run: status_closed, already_resolved, description_empty."
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Stable gap codes that do not stop a run on their own."
+        },
+        "summary": {
+          "type": "string",
+          "description": "The blockers and warnings rendered in outputLanguage. The one place this wording exists; maturity-followup.mjs quotes it rather than re-deriving it."
+        },
+        "accepted": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Gap codes a human explicitly waved through at the interactive maturity step. Recording WHICH gap was accepted is what separates an informed continue from a skipped check."
+        }
+      }
+    },
+    "maturityFollowup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gaps", "askedAt"],
+      "description": "v17.6.0+ - the record of an autopilot run having asked about an immature item (refs/features/maturity-followup.md). Absent means never asked, which is what makes the first pass distinguishable from every pass after it.",
+      "properties": {
+        "gaps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Sorted and deduplicated, so the next pass's comparison is stable rather than order-dependent."
+        },
+        "askedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["jira", "github", "confluence", "analysis", "unknown"]
+            },
+            "key": {
+              "type": ["string", "null"]
+            },
+            "url": {
+              "type": ["string", "null"]
+            }
+          }
+        },
+        "commentUrl": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "waitingFor": {
+      "type": "string",
+      "enum": ["maturity", "user-channels-choice"],
+      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. Declared as of v17.6.0: Phase 7's channels pause has written it since long before, and resume/SKILL.md never read it, so that pause was resumable only in prose. resume reads this first and falls back to currentPhase + 1 when it is absent. maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 7's channels menu, with the stored channelsInput."
+    },
     "workspaceSource": {
       "type": "string",
       "enum": ["asked", "command", "autopilot"],

package/pipeline/schemas/prefs.schema.json

@@ -969,6 +969,28 @@
             }
           }
         },
+        "maturityFollowup": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v17.6.0+ - what to do about an item the maturity check finds is not ready (refs/features/maturity-followup.md). The check has always produced a machine-readable gap list and then thrown it away: a blocker halted the run, the queue moved on, and the item stayed exactly as immature as it was found.",
+          "properties": {
+            "askInteractively": {
+              "type": "boolean",
+              "default": true,
+              "description": "An interactive blocker asks at the maturity step - open the item and fix it, continue without it (recording which gap was waved through), or abort - instead of ending the run with a summary. False restores the old halt."
+            },
+            "autopilotCommentsOnIssue": {
+              "type": "boolean",
+              "default": false,
+              "description": "OFF by default, and an outward-facing write. When on, an autopilot run posts ONE comment on the Jira or GitHub item asking for what is missing, then halts on the circuit breaker and waits for resume. A question, never a state change: no transition, no resolution, no assignee, no label, no close. The body uses Ref:, never Closes:/Fixes:/Resolves:, and its copy follows outputLanguage. It never comments twice for the same gap set - a changed item is re-checked, and only a DIFFERENT gap set earns a second comment."
+            },
+            "commentOnWarnings": {
+              "type": "boolean",
+              "default": false,
+              "description": "Treat warnings like blockers. Off by default because warnings have always auto-continued under autopilot, and converting them to halts in a release would stall queues overnight on items that ran fine yesterday. The gaps are recorded either way."
+            }
+          }
+        },
         "baseBranchEvidence": {
           "type": "object",
           "additionalProperties": false,
@@ -1975,6 +1997,19 @@
               "description": "Prefix of the identity label a created issue carries. The label is how a second run, on a second machine or by a second analyst, finds the tree it already made instead of opening a duplicate."
             }
           }
+        },
+        "mcpSurface": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v17.6.0+ - how many MCP servers this host has registered. Every registered server's tool list is charged against the context window on EVERY turn, and the user adds them one at a time without ever seeing the running total; our own toolkit contributes 99 tools by itself. `doctor` reports the count, it never disables anything.",
+          "properties": {
+            "infoAbove": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 8,
+              "description": "Report the registered-server count once it exceeds this. The number is JUDGEMENT, not a measurement - it exists so the threshold is visible and adjustable instead of hidden in the script. 0 reports the count always."
+            }
+          }
         }
       }
     },

package/pipeline/schemas/token-budget.json

@@ -13,7 +13,7 @@
       "max_tokens": 6500
     },
     "phase-3-dev": {
-      "max_tokens": 9300
+      "max_tokens": 9450
     },
     "phase-4-review": {
       "max_tokens": 15150
@@ -28,5 +28,5 @@
       "max_tokens": 6350
     }
   },
-  "total_max_tokens": 63000
+  "total_max_tokens": 63150
 }

package/pipeline/scripts/doctor.mjs

@@ -84,6 +84,7 @@ const CHECK_IDS = [
   "embedded-credentials",
   "task-tools",
   "mcp-registration",
+  "mcp-surface",
   "disk-space",
   "worktree-residue",
 ];
@@ -636,6 +637,69 @@ function checkMcpRegistration() {
   );
 }
 
+// How many MCP servers is this host paying for on every turn?
+//
+// checkMcpRegistration answers "is OURS registered". This answers the question the
+// user never gets asked: every registered server's tool list is sent with every
+// turn, they are added one at a time, and nobody sees the running total - our own
+// toolkit is 99 tools by itself. This check only ever REPORTS. It never disables
+// anything, and it never blocks or warns, because how many servers are worth their
+// context is the user's call and not a health failure.
+//
+// The threshold is judgement and is therefore a pref, not a constant hidden here:
+// `prefs.global.mcpSurface.infoAbove` (default 8). 0 reports the count always.
+function checkMcpSurface() {
+  // Three places a server can be declared, and all three are charged in the
+  // project the caller is standing in: the global config, the per-project block
+  // inside ~/.claude.json, and a .mcp.json committed to the repo. Counting only
+  // the global block understates exactly where it matters - a project-scoped
+  // server is invisible to the user for the same reason a global one is.
+  //
+  // Not counted, and said so in features/doctor.md: servers a marketplace plugin
+  // registers. Nothing in the config names them, and guessing a number is worse
+  // than reporting the one that is countable.
+  const cwd = process.cwd();
+  // The per-project key is matched by resolved path, not by string. On macOS /tmp
+  // and /var are symlinks, so the same directory has two spellings: the one the
+  // host wrote into its config and the one node reports. A string compare finds
+  // nothing on whichever side lost the race, and reports a smaller number with no
+  // sign that anything was missed.
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  const hereReal = real(cwd);
+  const names = new Set();
+  const add = (obj, scope) => {
+    for (const k of Object.keys(obj || {})) names.add(`${k} (${scope})`);
+  };
+  const home = readJson(join(HOME, ".claude.json"));
+  add(home?.mcpServers, "global");
+  add(readJson(join(CLAUDE, "settings.json"))?.mcpServers, "global");
+  for (const [dir, entry] of Object.entries(home?.projects || {})) {
+    if (real(dir) === hereReal) add(entry?.mcpServers, "this project");
+  }
+  add(readJson(join(cwd, ".mcp.json"))?.mcpServers, ".mcp.json");
+  const prefs = readJson(join(CLAUDE, "multi-agent-preferences.json"));
+  const raw = prefs?.global?.mcpSurface?.infoAbove;
+  const threshold = Number.isInteger(raw) && raw >= 0 ? raw : 8;
+  const sorted = [...names].sort();
+  if (sorted.length <= threshold) {
+    ok("mcp-surface");
+    return;
+  }
+  report(
+    "mcp-surface",
+    "INFO",
+    `${sorted.length} MCP servers are registered, and every one of them sends its tool list on every turn`,
+    "remove the servers this machine does not use (--explain lists them)",
+    sorted,
+  );
+}
+
 function checkDiskSpace() {
   let freeGb = null;
   try {
@@ -770,6 +834,7 @@ function main() {
   checkEmbeddedCredentials();
   checkTaskTools();
   checkMcpRegistration();
+  checkMcpSurface();
   checkDiskSpace();
   checkWorktreeResidue();
 

package/pipeline/scripts/feedback-send.mjs

@@ -31,7 +31,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const ENDPOINT_DEFAULT = "https://mmerterden.vercel.app/api/feedback/ingest";
+const ENDPOINT_DEFAULT = "https://mmerterden.com/api/feedback/ingest";
 const TIMEOUT_MS = 8000;
 const TEXT_MAX = 4000;
 const KINDS = new Set(["bug", "idea", "question"]);

package/pipeline/scripts/graph-report.mjs

@@ -34,6 +34,7 @@ import { execFileSync } from "node:child_process";
 import { join, dirname, resolve } from "node:path";
 import { parseFlags } from "./graph-build.mjs";
 import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+import { loadRules } from "./_code-graph.mjs";
 
 /**
  * Top-level source directory of a path, used as the module bucket.
@@ -86,7 +87,109 @@ export function summarize(graph, top) {
   const kinds = {};
   for (const s of symbols) kinds[s.symbolKind] = (kinds[s.symbolKind] || 0) + 1;
 
-  return { hubs, modules, externals, orphans, kinds, fileCount: files.length };
+  // The stack's rules say which symbol kinds can be reference targets at all.
+  // Without them the unreferenced question has no honest answer, so the section
+  // says that rather than listing symbols that never could have had an edge.
+  let referenceKinds;
+  try {
+    referenceKinds = loadRules(graph.stack).referenceKinds;
+  } catch {
+    // A stack with no rule file on disk, or one this build cannot parse. The
+    // section says so instead of guessing.
+    referenceKinds = null;
+  }
+  const unreferenced = referenceKinds ? unreferencedSymbols(graph, referenceKinds) : null;
+
+  return {
+    hubs,
+    modules,
+    externals,
+    orphans,
+    kinds,
+    fileCount: files.length,
+    referenceKinds,
+    unreferenced,
+  };
+}
+
+/**
+ * Symbols no OTHER file in this graph names.
+ *
+ * The orphan section finds FILES with no edge at all. A file imported for one
+ * symbol while three of its other exports are dead has edges, so it is invisible
+ * there - which is the gap this closes. The data needed was already in the graph:
+ * a symbol's only incoming edge kinds are `defines` (from its own file) and
+ * `references` (from another file).
+ *
+ * CANDIDATES, NOT VERDICTS. ADR-0010 records what the extractor is: regex over
+ * comment-stripped source, not a parser. Dynamic dispatch, reflection,
+ * string-keyed lookup, a public API consumed outside this repo, and anything
+ * reached through a name the rules do not treat as a reference target all look
+ * identical to dead code from here. So this reports and never gates, and the
+ * exclusions below exist so the list does not fill with symbols that COULD NOT
+ * have an edge no matter how heavily used they are:
+ *
+ *   - a nested declaration is never a reference target by construction
+ *   - a symbolKind outside this stack's referenceKinds is never a target
+ *   - a name declared in two places gets no reference edge at all (the builder
+ *     drops ambiguous tokens), so absence proves nothing about it
+ *   - a symbol declared in a test file is not the subject of this question
+ *
+ * Same-file use also produces no edge, so "unreferenced" here means precisely
+ * "no other file in this repo names it", which is what the section says.
+ *
+ * @param {object} graph
+ * @param {Set<string>|null} referenceKinds - null when the stack's rules did not load
+ * @returns {{candidates: object[], testOnly: object[], excluded: object}}
+ */
+export function unreferencedSymbols(graph, referenceKinds) {
+  const symbols = graph.nodes.filter((n) => n.kind === "symbol");
+  const fileById = new Map(graph.nodes.filter((n) => n.kind === "file").map((n) => [n.id, n]));
+
+  const nameCount = new Map();
+  for (const sym of symbols) {
+    if (sym.nested === true) continue;
+    nameCount.set(sym.name, (nameCount.get(sym.name) || 0) + 1);
+  }
+
+  const incoming = new Map();
+  for (const e of graph.edges) {
+    if (e.kind !== "references") continue;
+    if (!incoming.has(e.to)) incoming.set(e.to, []);
+    incoming.get(e.to).push(e.from);
+  }
+
+  const excluded = { nested: 0, kindNotATarget: 0, ambiguousName: 0, test: 0 };
+  const candidates = [];
+  const testOnly = [];
+
+  for (const sym of symbols) {
+    if (sym.isTest) {
+      excluded.test += 1;
+      continue;
+    }
+    if (sym.nested === true) {
+      excluded.nested += 1;
+      continue;
+    }
+    if (referenceKinds && !referenceKinds.has(sym.symbolKind)) {
+      excluded.kindNotATarget += 1;
+      continue;
+    }
+    if ((nameCount.get(sym.name) || 0) > 1) {
+      excluded.ambiguousName += 1;
+      continue;
+    }
+    const from = incoming.get(sym.id) || [];
+    if (from.length === 0) {
+      candidates.push(sym);
+      continue;
+    }
+    if (from.every((fid) => fileById.get(fid)?.isTest === true)) testOnly.push(sym);
+  }
+
+  const bySymbol = (a, b) => a.path.localeCompare(b.path) || a.name.localeCompare(b.name);
+  return { candidates: candidates.sort(bySymbol), testOnly: testOnly.sort(bySymbol), excluded };
 }
 
 /**
@@ -160,6 +263,57 @@ export function render(graph, top) {
   }
   L.push("");
 
+  L.push(`## Symbols nothing else references`);
+  L.push("");
+  if (!s.referenceKinds) {
+    L.push(
+      `Not computed: this stack's code-graph rules did not load, so which symbol kinds can be ` +
+        `reference targets at all is unknown, and every answer would be a guess.`,
+    );
+  } else {
+    const u = s.unreferenced;
+    L.push(
+      `Candidates, not verdicts. These are symbols no OTHER file in this repo names. ` +
+        `The extractor is regex over comment-stripped source, not a parser, so dynamic dispatch, ` +
+        `reflection, string-keyed lookup and a public API consumed outside this repo all look ` +
+        `exactly like dead code from here. Nothing gates on this list.`,
+    );
+    L.push("");
+    L.push(
+      `Excluded because they could not carry a reference edge either way: ` +
+        `${u.excluded.kindNotATarget} of a kind this stack never treats as a target, ` +
+        `${u.excluded.ambiguousName} declared under a name that exists in more than one place, ` +
+        `${u.excluded.nested} nested, ${u.excluded.test} declared in test files.`,
+    );
+    L.push("");
+    if (u.candidates.length === 0) {
+      L.push(`None: every eligible symbol is named by at least one other file.`);
+    } else {
+      L.push(`${u.candidates.length} symbol(s) with no reference from any other file:`);
+      L.push("");
+      L.push(`| Symbol | Kind | Path |`);
+      L.push(`|---|---|---|`);
+      for (const c of u.candidates.slice(0, top)) {
+        L.push(`| \`${c.name}\` | ${c.symbolKind} | \`${c.path}:${c.line || 1}\` |`);
+      }
+      if (u.candidates.length > top) L.push("");
+      if (u.candidates.length > top) L.push(`... ${u.candidates.length - top} more`);
+    }
+    L.push("");
+    if (u.testOnly.length > 0) {
+      L.push(
+        `${u.testOnly.length} more are referenced ONLY from test files. That is not dead code - ` +
+          `it is code whose only consumer is its own test, which is worth knowing before a plan ` +
+          `treats it as load-bearing:`,
+      );
+      L.push("");
+      for (const t of u.testOnly.slice(0, top))
+        L.push(`- \`${t.name}\` - \`${t.path}:${t.line || 1}\``);
+      if (u.testOnly.length > top) L.push(`- ... ${u.testOnly.length - top} more`);
+      L.push("");
+    }
+  }
+
   return L.join("\n");
 }