@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/schemas/test-gen-gaps.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gen-gaps.schema.json",
+  "title": "Multi-Agent Pipeline  -  test-gen gaps",
+  "description": "The gap analysis of /multi-agent:test-gen, $RUN/gaps.json (multi-agent-refs/test-gen/stages.md). Written from the read-only analyst's answer: the selected inventory items set against the existing tests, each gap a scenario to write. `wrongly-covered` (a test exists but cannot see the failure) is kept apart from `missing`. dataNeeds[] says what test data a scenario needs and who provides it; it never holds a value, because values are entered by a person or resolved by secret reference at run time. unmeasured[] lists what the analysis could not measure, which is not the same as covered. test-gen-gate.mjs check --stage gaps checks this shape without a dependency.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "coverage", "gaps", "dataNeeds", "unmeasured"],
+  "$defs": {
+    "fileLine": { "type": "string", "pattern": "^[^\\s:]+:[1-9][0-9]*$" }
+  },
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "measured"],
+      "properties": {
+        "method": {
+          "enum": ["coverage_gap", "agent"],
+          "description": "coverage_gap: the toolkit tool joined inventory and tests by identifier; agent: the analyst's own reading, on a toolkit without the tool."
+        },
+        "measured": { "type": "boolean" },
+        "reason": { "type": "string", "minLength": 1 },
+        "covered": { "type": "integer", "minimum": 0 },
+        "uncovered": { "type": "integer", "minimum": 0 },
+        "unmatched": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "inventoryId",
+          "bucket",
+          "title",
+          "priority",
+          "rationale",
+          "expectation",
+          "automation",
+          "method"
+        ],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "inventoryId": { "type": "string", "minLength": 1 },
+          "bucket": { "enum": ["missing", "wrongly-covered"] },
+          "title": { "type": "string", "minLength": 1 },
+          "priority": {
+            "enum": ["bug-catching", "edge", "basic"],
+            "description": "bug-catching: would catch a failure users hit; edge: a boundary or error path; basic: the happy path."
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the business cares."
+          },
+          "expectation": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the test asserts, measurable."
+          },
+          "automation": { "enum": ["yes", "no", "needs-code"] },
+          "method": {
+            "enum": ["exact", "inferred"],
+            "description": "exact: matched by identifier; inferred: the analyst's judgement, kept apart."
+          },
+          "evidence": { "type": "array", "items": { "$ref": "#/$defs/fileLine" } },
+          "handlesNeeded": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["target", "suggestion"],
+              "properties": {
+                "target": { "type": "string", "minLength": 1 },
+                "suggestion": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "dataNeeds": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "gapIds", "what", "kind"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "gapIds": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "what": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["account", "seed", "fixture", "secret", "other"] },
+          "secretRef": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Credential name a test resolves at run time; never the value."
+          }
+        }
+      }
+    },
+    "unmeasured": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reason"],
+        "properties": {
+          "inventoryId": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/test-gen-inventory.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gen-inventory.schema.json",
+  "title": "Multi-Agent Pipeline  -  test-gen inventory",
+  "description": "What the app has that a test could cover, written by the inventory stage of /multi-agent:test-gen as $RUN/inventory.json (multi-agent-refs/test-gen/stages.md). Items are joined to tests by their stable id (route, screen id, Figma node id, endpoint path), never by title. `priority` is added after the inventory, from the user's pick or, in autopilot, the top three. test-gen-gate.mjs check --stage inventory checks this shape without a dependency.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "platform", "source", "items"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "platform": { "enum": ["ios", "android", "web", "api"] },
+    "repo": { "type": "string", "minLength": 1 },
+    "source": {
+      "enum": ["design_scenario_inventory", "web_map", "ui_tree", "openapi", "agent"],
+      "description": "Where the items came from. `agent` is the stage's own reading of the code, used when no tool answered."
+    },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "title"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "description": "Stable identifier." },
+          "kind": { "enum": ["screen", "flow", "endpoint", "component"] },
+          "title": { "type": "string", "minLength": 1 },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Code path that implements it, file or directory."
+          },
+          "handles": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Automation handles already on it (accessibilityIdentifier, testTag, data-testid)."
+          }
+        }
+      }
+    },
+    "priority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "selected"],
+      "properties": {
+        "mode": {
+          "enum": ["user", "autopilot-top3"],
+          "description": "user: picked by the person; autopilot-top3: the three the run proceeded with unattended."
+        },
+        "selected": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/test-gen-results.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gen-results.schema.json",
+  "title": "Multi-Agent Pipeline  -  test-gen results",
+  "description": "The outcome of the tests /multi-agent:test-gen wrote, $RUN/results.json, built by test-gen-gate.mjs results from the classify stage (multi-agent-refs/features/test-classification.md). Three states: pass, fail, not_measured; anything but pass carries its reason. `classification` keeps the measured class behind the state (an unstable test is a fail, a test with no base is not_measured), and `triage` the result-triage verdict once one is made. test-gen-gate.mjs check --stage results checks this shape without a dependency.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "source", "green", "tests", "summary"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "source": { "enum": ["toolkit", "fallback"] },
+    "green": { "type": "boolean" },
+    "tests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "file": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["pass", "fail", "not_measured"] },
+          "classification": {
+            "enum": ["passed", "regression", "preexisting", "unstable", "not_measured"]
+          },
+          "reason": { "type": "string", "minLength": 1 },
+          "triage": { "enum": ["product-bug", "stale-test", "new-scenario", "valid", "ambiguous"] }
+        },
+        "if": { "properties": { "status": { "enum": ["fail", "not_measured"] } } },
+        "then": { "required": ["reason"] }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pass", "fail", "not_measured"],
+      "properties": {
+        "pass": { "type": "integer", "minimum": 0 },
+        "fail": { "type": "integer", "minimum": 0 },
+        "not_measured": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/pipeline/scripts/_active-run.mjs

@@ -0,0 +1,158 @@
+/**
+ * @file _active-run.mjs  -  which pipeline run a hook call belongs to, and where
+ * that run stands against its mode's phase list.
+ *
+ * A hook receives the host's session id and working directory, never a task id.
+ * A run is bound to a session by one of three facts, strongest first:
+ *
+ *   1. `sessionId` equals MULTI_AGENT_SESSION_ID in the hook's environment: the
+ *      id a launcher started the run with (continuous mode, a client).
+ *   2. `hostSessionId` equals the payload's `session_id`: write-state.mjs stamps
+ *      the host session that made the run's last phase transition
+ *      (CLAUDE_CODE_SESSION_ID), so the session driving a run is the one bound
+ *      to it, and a resume in a new session rebinds it at its first transition.
+ *   3. A state with no `hostSessionId` whose `worktreePath` is the git toplevel
+ *      of the payload's cwd: a run written before the stamp existed. A state
+ *      that carries a different `hostSessionId` is another session's run and
+ *      never matches this way.
+ *
+ * Nothing here decides anything; callers (run-stop-guard, run-scope-guard)
+ * apply their own rule to the run this returns. Zero runtime dependencies.
+ *
+ * @module pipeline/scripts/_active-run
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { listRuns, logsRoot, resolveRunFile } from "./_run-paths.mjs";
+
+export {
+  finalPhaseOf,
+  modeOf,
+  modePhases,
+  nextPhaseOf,
+  phaseContract,
+  phaseName,
+} from "../lib/run-completion.mjs";
+
+function real(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** The git toplevel of `dir`, real-pathed, or null outside a repository. */
+export function gitToplevel(dir) {
+  if (!dir) return null;
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return r.status === 0 ? real(r.stdout.trim()) : null;
+}
+
+function mtime(p) {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+const LIVE_STATUSES = new Set(["in_progress", "awaiting_input"]);
+
+/**
+ * The run bound to this hook call, or null.
+ *
+ * @param {{sessionId?: string|null, cwd?: string|null, env?: Record<string,string|undefined>}} opts
+ * @returns {{statePath: string, state: object, matchedBy: "session"|"host-session"|"worktree"} | null}
+ *   with `unreadable` (count of state files that did not parse) on the returned
+ *   object or on the `findActiveRun.lastUnreadable` property when nothing matched
+ */
+export function findActiveRun({ sessionId = null, cwd = null, env = process.env } = {}) {
+  const launched = env.MULTI_AGENT_SESSION_ID || "";
+  let top;
+  const topOf = () => {
+    if (top === undefined) top = cwd ? gitToplevel(cwd) : null;
+    return top;
+  };
+  const hits = [];
+  let unreadable = 0;
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    for (const run of listRuns()) {
+      const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+      if (!p) continue;
+      const doc = readRegularJson(p, null);
+      if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        unreadable += 1;
+        continue;
+      }
+      let matchedBy = null;
+      if (launched && doc.sessionId === launched) matchedBy = "session";
+      else if (sessionId && doc.hostSessionId === sessionId) matchedBy = "host-session";
+      else if (
+        !doc.hostSessionId &&
+        typeof doc.worktreePath === "string" &&
+        doc.worktreePath &&
+        topOf() &&
+        real(doc.worktreePath) === topOf()
+      ) {
+        matchedBy = "worktree";
+      }
+      if (matchedBy) hits.push({ statePath: p, state: doc, matchedBy, t: mtime(p) });
+    }
+  } finally {
+    if (prevRoot === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = prevRoot;
+  }
+  findActiveRun.lastUnreadable = unreadable;
+  if (!hits.length) return null;
+  const rank = { session: 0, "host-session": 1, worktree: 2 };
+  hits.sort((a, b) => rank[a.matchedBy] - rank[b.matchedBy] || b.t - a.t);
+  const lead = hits.filter((h) => h.matchedBy === hits[0].matchedBy);
+  // A session can hold a finished run next to a live one. The run started
+  // last is the one the session is on: a live run started after the finished
+  // one wins however recently the finished file was touched, and a live run
+  // started before it was abandoned without a halt and does not hold the
+  // session. startedAt orders them; the state's mtime stands in without it.
+  const started = (h) => Date.parse(h.state?.startedAt) || h.t;
+  const isLive = (h) => LIVE_STATUSES.has(h.state?.status);
+  const liveRun = lead.find(isLive);
+  const finished = lead.filter((h) => !isLive(h));
+  const lastFinished = finished.sort((a, b) => started(b) - started(a))[0];
+  let pick = lead[0];
+  if (liveRun)
+    pick = lastFinished && started(lastFinished) > started(liveRun) ? lastFinished : liveRun;
+  const { t: _t, ...best } = pick;
+  return { ...best, unreadable };
+}
+findActiveRun.lastUnreadable = 0;
+
+/**
+ * Append one line to the hook failure log under the log root. A hook that
+ * fails open says why somewhere a person can read later; this never throws.
+ *
+ * @param {string} hook
+ * @param {string} reason
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function logHookFailure(hook, reason, env = process.env) {
+  try {
+    const root = env.LOGS_ROOT || logsRoot();
+    mkdirSync(root, { recursive: true });
+    const line = `${new Date().toISOString()} ${hook}: ${String(reason).replace(/\s+/g, " ")}\n`;
+    appendFileSync(join(root, "hook-failures.log"), line);
+  } catch {
+    // Logging is best-effort; the hook's verdict never depends on it.
+  }
+}
+
+/** The run directory that holds a state file. */
+export const runDirOf = (statePath) => dirname(statePath);

package/pipeline/scripts/_autopilot-outcomes.mjs

@@ -27,6 +27,7 @@ export const OUTCOME = Object.freeze({
   MERGED: "merged",
   SKIPPED: "skipped",
   COMPLETED_NO_PR: "completed-no-pr",
+  STOPPED_INCOMPLETE: "stopped-incomplete",
   NEEDS_INPUT: "needs-input",
   AWAITING_ANSWER: "awaiting-answer",
   VERIFICATION_FAILED: "verification-failed",