@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/schemas/migrations/state-2.1.0-to-2.2.0.mjs

@@ -0,0 +1,129 @@
+/**
+ * state-2.1.0-to-2.2.0.mjs  -  agent-state migration
+ *
+ * v19.0.0 collapsed the eight-phase contract (0..7) into six (0..5). This is
+ * the first migration in the repo that rewrites phase NUMBERS, so it is also
+ * the first one where two source keys can land on one target key.
+ *
+ *   0 Init      -> 0 Init
+ *   1 Analysis  -> 1 Plan
+ *   2 Planning  -> 1 Plan
+ *   3 Dev       -> 2 Dev
+ *   4 Review    -> 3 Review
+ *   5 Test      -> 3 Review
+ *   6 Commit    -> 4 Commit
+ *   7 Report    -> 5 Report
+ *
+ * Collision rule for `phases{}`: the furthest-along status wins, retryCount
+ * takes the max, files[] union, startedAt earliest, finishedAt latest. Taking
+ * the max of retryCount rather than the sum matters - the schema caps it at 3
+ * and a sum of two 2s would emit an invalid state.
+ *
+ * The migration also repairs three defects the 62-file live corpus carries
+ * today, because a run that cannot be validated cannot be resumed either:
+ *   - `status: "completed"` -> "complete" (never was in the enum)
+ *   - `status: "awaiting-user-test-main-checkout"` -> "awaiting_input"
+ *     (the schema's own description spells this substitution out)
+ *   - missing `currentPhase` / `status` -> explicit defaults, so the file
+ *     validates instead of failing on absence
+ *
+ * @param {object} data  -  parsed agent-state.json
+ * @returns {object}     -  migrated data with schemaVersion "2.2.0"
+ */
+
+const PHASE_MAP = { 0: 0, 1: 1, 2: 1, 3: 2, 4: 3, 5: 3, 6: 4, 7: 5 };
+
+// Furthest-along wins. A phase that failed outranks one still pending: the
+// failure is the fact a resume needs, and losing it would make the merged
+// phase look untouched.
+const STATUS_RANK = { pending: 0, skipped: 1, in_progress: 2, failed: 3, done: 4 };
+
+const RUN_STATUS_FIX = {
+  completed: "complete",
+  "awaiting-user-test-main-checkout": "awaiting_input",
+};
+
+function earlier(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return a < b ? a : b;
+}
+
+function later(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return a > b ? a : b;
+}
+
+function mergePhase(into, from) {
+  if (!into) return { ...from };
+  const out = { ...into };
+
+  const rankA = STATUS_RANK[into.status] ?? -1;
+  const rankB = STATUS_RANK[from.status] ?? -1;
+  if (rankB > rankA) out.status = from.status;
+
+  if (from.retryCount !== undefined || into.retryCount !== undefined) {
+    out.retryCount = Math.max(into.retryCount ?? 0, from.retryCount ?? 0);
+  }
+
+  if (Array.isArray(into.files) || Array.isArray(from.files)) {
+    out.files = [...new Set([...(into.files ?? []), ...(from.files ?? [])])];
+  }
+
+  const startedAt = earlier(into.startedAt, from.startedAt);
+  if (startedAt) out.startedAt = startedAt;
+  const finishedAt = later(into.finishedAt, from.finishedAt);
+  if (finishedAt) out.finishedAt = finishedAt;
+
+  // Notes are prose from two different phases; concatenating keeps both
+  // rather than silently picking one.
+  if (into.notes && from.notes && into.notes !== from.notes) {
+    out.notes = `${into.notes}\n${from.notes}`;
+  } else if (from.notes && !into.notes) {
+    out.notes = from.notes;
+  }
+
+  // Every remaining key the later source carries and the earlier one does not.
+  for (const [k, v] of Object.entries(from)) {
+    if (out[k] === undefined) out[k] = v;
+  }
+
+  return out;
+}
+
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.2.0";
+
+  if (Number.isInteger(out.currentPhase) && PHASE_MAP[out.currentPhase] !== undefined) {
+    out.currentPhase = PHASE_MAP[out.currentPhase];
+  } else if (!Number.isInteger(out.currentPhase)) {
+    // 9 of the 62 live files have no currentPhase at all. Resume keys on this
+    // field, so absence is not a neutral state - it is a file resume cannot
+    // read. Init is the only phase that is safe to re-enter unconditionally.
+    out.currentPhase = 0;
+  }
+
+  if (out.phases && typeof out.phases === "object" && !Array.isArray(out.phases)) {
+    const merged = {};
+    // Ascending key order so the later phase merges INTO the earlier one and
+    // `notes` concatenate in the order they were written.
+    const keys = Object.keys(out.phases).sort((a, b) => Number(a) - Number(b));
+    for (const key of keys) {
+      const mappedKey = PHASE_MAP[Number(key)];
+      if (mappedKey === undefined) continue; // unmappable key is dropped, not guessed
+      merged[String(mappedKey)] = mergePhase(merged[String(mappedKey)], out.phases[key]);
+    }
+    out.phases = merged;
+  }
+
+  if (typeof out.status === "string" && RUN_STATUS_FIX[out.status]) {
+    out.status = RUN_STATUS_FIX[out.status];
+  } else if (typeof out.status !== "string") {
+    out.status = "failed";
+  }
+
+  return out;
+}

package/pipeline/schemas/phases.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.json",
+  "description": "The phase contract, in one place. Before this file the phase list existed as eight independent copies - gen-mode-dispatch.mjs, phases.md twice, phase-tracker.sh, render-work-summary.sh, agent-state.schema.json, token-budget.json, docs/architecture.md - and none derived from another, so a renumbering meant eight hand edits and the count in prose was guarded by nothing. smoke-phase-contract.sh reads this file and holds every other copy to it. Adding or merging a phase means editing here; everywhere else either reads this or is checked against it. Ceilings are re-measured after the docs merge (Faz F), not summed from the old ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement, so summing would ship a stale ceiling by construction.",
+  "contractVersion": "2.0.0",
+  "phaseSchema": 2,
+  "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
+  "legacyPhaseNames": {
+    "note": "Generation 1 phase names, kept so an aggregator can label a historical metrics.jsonl row correctly instead of printing the current name for a number that meant something else. Read-only history: nothing emits these any more. The generation 1 -> 2 number map is not repeated here, it is the `was` array on each phase above.",
+    "0": "Init",
+    "1": "Analysis",
+    "2": "Planning",
+    "3": "Dev",
+    "4": "Review",
+    "5": "Test",
+    "6": "Commit",
+    "7": "Report"
+  },
+  "phases": [
+    {
+      "id": 0,
+      "name": "Init",
+      "doc": "phase-0-init.md",
+      "maxTokens": 13400,
+      "was": [0]
+    },
+    {
+      "id": 1,
+      "name": "Plan",
+      "doc": "phase-1-plan.md",
+      "maxTokens": 10000,
+      "was": [1, 2]
+    },
+    {
+      "id": 2,
+      "name": "Dev",
+      "doc": "phase-2-dev.md",
+      "maxTokens": 10650,
+      "was": [3]
+    },
+    {
+      "id": 3,
+      "name": "Review",
+      "doc": "phase-3-review.md",
+      "maxTokens": 17200,
+      "was": [4, 5]
+    },
+    {
+      "id": 4,
+      "name": "Commit",
+      "doc": "phase-4-commit.md",
+      "maxTokens": 6500,
+      "was": [6]
+    },
+    {
+      "id": 5,
+      "name": "Report",
+      "doc": "phase-5-report.md",
+      "maxTokens": 5550,
+      "was": [7]
+    }
+  ],
+  "totalMaxTokens": 63300,
+  "modes": {
+    "full": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "local": false,
+      "autopilot": false,
+      "depth": true
+    },
+    "autopilot": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "local": false,
+      "autopilot": true
+    },
+    "local": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "local": true,
+      "autopilot": false,
+      "depth": true
+    },
+    "local-autopilot": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "local": true,
+      "autopilot": true
+    },
+    "full-local": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "local": true,
+      "autopilot": false,
+      "depth": true
+    },
+    "analysis": {
+      "phases": [0, 1, 3, 4, 5],
+      "local": false,
+      "autopilot": false
+    }
+  },
+  "thresholds": {
+    "waitingFromPhase": 4,
+    "mcpAllowedThroughPhase": 1,
+    "shortRunFromPhase": 2,
+    "note": "Phase numbers other code compares against, named here so a renumbering moves them with the contract. waitingFromPhase: runs-index.mjs groups a run as 'waiting on you' from Commit on. mcpAllowedThroughPhase: Figma MCP is reachable only through Plan; smoke-no-mcp-in-dev-phases.sh fails any recorded call at a higher phase. Its literal threshold is unchanged from the eight-phase contract on purpose - Analysis was 1 and is now inside Plan, also 1, so the permitted set {0,1} is identical. shortRunFromPhase: the depth picker's Short set starts here."
+  }
+}

package/pipeline/schemas/plan-todos.schema.json

@@ -2,19 +2,19 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://example.com/pipeline/plan-todos.schema.json",
   "title": "Plan Todo List",
-  "description": "Structured representation of Phase 2's plan. Persists into agent-state under `.plan.todos[]` and survives across phases. Phase 3 (Dev) iterates step-by-step; Phase 4 (Review) verifies completed steps against criteria; Phase 7 (Report) renders a per-step rollup. The plan is broken into a live, structured Todo list for step-by-step tracking across phases.",
+  "description": "Structured representation of Phase 2's plan. Persists into agent-state under `.plan.todos[]` and survives across phases. Phase 3 (Dev) iterates step-by-step; Phase 4 (Review) verifies completed steps against criteria; Phase 5 (Report) renders a per-step rollup. The plan is broken into a live, structured Todo list for step-by-step tracking across phases.",
   "type": "object",
   "additionalProperties": false,
   "required": ["title", "todos"],
   "properties": {
     "title": {
       "type": "string",
-      "description": "One-line plan summary, mirrors the task title. Surfaced in Phase 3 progress lines and Phase 7 report."
+      "description": "One-line plan summary, mirrors the task title. Surfaced in Phase 3 progress lines and Phase 5 report."
     },
     "createdAt": {
       "type": "string",
       "format": "date-time",
-      "description": "ISO-8601 timestamp Phase 2 emitted this plan. Used by Phase 7 for elapsed-time math."
+      "description": "ISO-8601 timestamp Phase 2 emitted this plan. Used by Phase 5 for elapsed-time math."
     },
     "todos": {
       "type": "array",
@@ -49,7 +49,7 @@
           "completedAt": { "type": "string", "format": "date-time" },
           "notes": {
             "type": "string",
-            "description": "Free-text outcome  -  commit hash, test count, anything Phase 7 should echo."
+            "description": "Free-text outcome  -  commit hash, test count, anything Phase 5 should echo."
           },
           "failureReason": { "type": "string" },
           "skipReason": { "type": "string" },
@@ -61,7 +61,7 @@
           "estimatedMinutes": {
             "type": "integer",
             "minimum": 1,
-            "description": "Optional Phase 2 estimate for the step. Phase 7 compares against actual duration."
+            "description": "Optional Phase 2 estimate for the step. Phase 5 compares against actual duration."
           }
         }
       }

package/pipeline/schemas/planning-output.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/planning-output.schema.json",
   "version": "1.0.0",
-  "title": "Multi-Agent Pipeline  -  Phase 2 planning output",
+  "title": "Multi-Agent Pipeline  -  Phase 1 planning output",
   "description": "Contract for Phase 2 task decomposition. Consumed by Phase 3 TDD cycles  -  each task becomes one red→green→refactor iteration.",
   "type": "object",
   "additionalProperties": false,