@mmerterden/multi-agent-pipeline 16.15.0 → 16.16.0

package/pipeline/multi-agent-refs/phases.md

@@ -26,6 +26,44 @@ Short:     0-Init -> (1,2 skipped) --------------> 3-Dev -> 4-Review -> 5-Test -
 Full or Short is the Phase 0 Step 7.5 question, not a command name. Autopilot never asks and always runs Full.
 ```
 
+## Phase entry  -  pending steer (every phase, every mode)
+
+Before a phase does any work, read `pendingSteer` from `agent-state.json`. It
+is how a correction reaches a run that is already going: `/multi-agent:steer #N
+"<instruction>"` queues one, and the next phase to start consumes it.
+
+```bash
+STEER=$(node -e 'try{const s=require(process.argv[1]);const p=s.pendingSteer;if(p&&p.text&&!p.appliedAt)process.stdout.write(p.text)}catch{}' "$STATE_FILE")
+```
+
+The `catch` is not decoration: a state file that does not exist yet (Phase 0
+before its first write) makes `require` throw, and an unguarded read prints a
+stack trace at every phase entry that reads like a failed phase.
+
+Empty → carry on, nothing to do. Non-empty:
+
+1. Apply it to this phase's context before starting. It is the user's own
+   words; treat it as an instruction from them, arriving now.
+2. Say what changed, in one line, so the correction is visible in the run and
+   not only in the state file.
+3. Mark it consumed. The record stays as a trace; `appliedAt` is what stops it
+   being read again, and the next steer overwrites all four keys:
+   ```bash
+   printf '{"pendingSteer":{"appliedAt":"%s","appliedPhase":<N>}}' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+     | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+   ```
+
+   `<N>` is this phase's number, substituted literally and unquoted - it is a
+   JSON number. Leaving it as an unset shell variable produces
+   `"appliedPhase":}`, which is invalid JSON and exits 1.
+4. Record it on the tracker and in the log: `bash $HOME/.claude/scripts/phase-tracker.sh meta <N> steer "applied"`, plus a `Steer applied: <text>` line in `agent-log.md`.
+
+Two limits, both deliberate. It is read at phase **entry** only, never mid-phase:
+a phase that changes target halfway discards the work it already did, which is
+the outcome steer exists to avoid. And an instruction that contradicts an
+approved plan halts for the user rather than silently rewriting the plan -
+steering corrects a run, it does not re-authorize one.
+
 ## Visual Phase Tracker
 
 Two channels run in parallel at every phase boundary. Both are required in their target CLIs  -  skipping either is the #1 source of "I see no progress" complaints.

package/pipeline/preferences-template.json

@@ -48,12 +48,7 @@
       "autoDiff": false,
       "manualNote": false
     },
-    "wikiScope": [
-      "main",
-      "ios",
-      "screenshots",
-      "index"
-    ],
+    "wikiScope": ["main", "ios", "screenshots", "index"],
     "autopilotReportTimeoutSeconds": 1800,
     "promptLanguage": "en",
     "outputLanguage": "en",
@@ -185,10 +180,7 @@
       "localPath": "plugins/<my-plugin>/skills/workflow",
       "upstreamMarketplace": "<installed-marketplace-name>",
       "upstreamPlugin": "<upstream-plugin-name>",
-      "upstreamSkills": [
-        "<skill-a>",
-        "<skill-b>"
-      ],
+      "upstreamSkills": ["<skill-a>", "<skill-b>"],
       "derivedFromVersion": "0.0.0",
       "upstreamVersionSource": "marketplace.json",
       "upstreamLocalClone": "$HOME/<upstream-repo-working-copy>",

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

@@ -104,6 +104,41 @@
       "type": ["string", "null"],
       "description": "Set when a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable). Format '<phase>:<cause>'. Surfaced to the user and cleared on successful resume. See operations.md 'Halt visibility'."
     },
+    "rev": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic revision, bumped by write-state.mjs on every successful write. A reader keeps the rev it read and compares before writing back; a changed rev means the record moved underneath it. Optional, so a record written by an earlier version stays valid: treat a missing rev as 0. No schemaVersion bump - the field is additive and nothing needs migrating."
+    },
+    "pendingSteer": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["text", "at"],
+      "description": "A mid-run instruction from the user, waiting for the next phase boundary to consume it. Written by /multi-agent:steer; a phase consumes it at entry by setting appliedAt, which is what stops it being read again. The record is kept as a trace and overwritten wholesale by the next steer. Never applied mid-phase: changing the target of work already in flight throws that work away.",
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000,
+          "description": "The instruction, verbatim as the user typed it."
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When it was queued."
+        },
+        "appliedAt": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "When a phase consumed it. Set alongside clearing the record, so the log keeps the trace."
+        },
+        "appliedPhase": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "maximum": 7,
+          "description": "The phase that consumed it."
+        }
+      }
+    },
     "telemetry": {
       "type": "object",
       "additionalProperties": true,

package/pipeline/schemas/analysis-spec.schema.json

@@ -104,7 +104,10 @@
     "platforms": {
       "type": "array",
       "minItems": 1,
-      "items": { "type": "string", "enum": ["ios", "android", "web", "backend", "mobile", "frontend"] },
+      "items": {
+        "type": "string",
+        "enum": ["ios", "android", "web", "backend", "mobile", "frontend"]
+      },
       "description": "Platforms selected in Phase 0 step 3 (multi-select)."
     },
     "repos": {
@@ -114,7 +117,10 @@
         "additionalProperties": false,
         "required": ["platform", "name", "canPush"],
         "properties": {
-          "platform": { "type": "string", "enum": ["ios", "android", "web", "backend", "mobile", "frontend"] },
+          "platform": {
+            "type": "string",
+            "enum": ["ios", "android", "web", "backend", "mobile", "frontend"]
+          },
           "name": { "type": "string", "minLength": 1 },
           "cloneUrl": { "type": ["string", "null"] },
           "canPush": { "type": "boolean" }

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

@@ -66,13 +66,7 @@
     "conventionBucket": {
       "type": "object",
       "additionalProperties": false,
-      "required": [
-        "pattern",
-        "example",
-        "confidence",
-        "evidenceFiles",
-        "alternativeCandidates"
-      ],
+      "required": ["pattern", "example", "confidence", "evidenceFiles", "alternativeCandidates"],
       "properties": {
         "pattern": {
           "type": "string",
@@ -84,12 +78,7 @@
         },
         "confidence": {
           "type": "string",
-          "enum": [
-            "high",
-            "medium",
-            "low",
-            "none"
-          ],
+          "enum": ["high", "medium", "low", "none"],
           "description": "high: 5+ examples; medium: 3-4; low: 1-2 or mixed; none: no evidence."
         },
         "evidenceFiles": {

package/pipeline/scripts/build-references.mjs

@@ -34,7 +34,7 @@ const NONE = "-";
 
 function argOf(argv, flag) {
   const i = argv.indexOf(flag);
-  return i === -1 ? null : argv[i + 1] ?? null;
+  return i === -1 ? null : (argv[i + 1] ?? null);
 }
 
 function readState(path) {
@@ -102,15 +102,27 @@ function rowsFrom(spec, lang) {
       c.url,
       ref || NONE,
       c.embeddedApiTable
-        ? lang === "tr" ? "API kontratı" : "API contract"
-        : lang === "tr" ? "özellik spesifikasyonu" : "feature spec",
+        ? lang === "tr"
+          ? "API kontratı"
+          : "API contract"
+        : lang === "tr"
+          ? "özellik spesifikasyonu"
+          : "feature spec",
       OK[lang],
       NONE,
     );
   }
 
   for (const j of ev.jira ?? []) {
-    push("Jira", j.id, j.url ?? NONE, NONE, lang === "tr" ? "ticket" : "ticket", OK[lang], j.summary);
+    push(
+      "Jira",
+      j.id,
+      j.url ?? NONE,
+      NONE,
+      lang === "tr" ? "ticket" : "ticket",
+      OK[lang],
+      j.summary,
+    );
   }
 
   for (const s of ev.swagger ?? []) {
@@ -266,13 +278,17 @@ function tableLocators(block) {
   const found = [];
   for (const line of block.split(/\r?\n/)) {
     if (!line.trim().startsWith("|")) continue;
-    const cells = line.split("|").slice(1, -1).map((c) => c.trim());
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((c) => c.trim());
     if (cells.length < 3) continue;
     if (/^:?-{3,}:?$/.test(cells[0])) continue;
     const locator = cells[2];
     const source = cells[1];
     if (!locator) continue;
-    if (HEADER_CELLS.has(locator.toLowerCase()) && HEADER_CELLS.has(cells[0].toLowerCase())) continue;
+    if (HEADER_CELLS.has(locator.toLowerCase()) && HEADER_CELLS.has(cells[0].toLowerCase()))
+      continue;
     found.push({ locator, source, raw: line });
   }
   return found;

package/pipeline/scripts/code-graph-rules/android.json

@@ -3,19 +3,9 @@
   "stack": "android",
   "description": "Kotlin + Java code-graph rules. Adds what the graph needs on top of test-gap-rules/android.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants internal types too, because Phase 1 narrows scope on the whole module, not just its public surface.",
   "comments": {
-    "line": [
-      "//"
-    ],
-    "block": [
-      [
-        "/*",
-        "*/"
-      ]
-    ],
-    "string": [
-      "\"\"\"",
-      "\""
-    ]
+    "line": ["//"],
+    "block": [["/*", "*/"]],
+    "string": ["\"\"\"", "\""]
   },
   "definitionPatterns": [
     {
@@ -60,14 +50,7 @@
       "regex": "^\\s*import\\s+(?:static\\s+)?(?:[A-Za-z_][A-Za-z0-9_]*\\.)+([A-Z][A-Za-z0-9_]*)"
     }
   ],
-  "referenceKinds": [
-    "class",
-    "interface",
-    "object",
-    "enum",
-    "record",
-    "typealias"
-  ],
+  "referenceKinds": ["class", "interface", "object", "enum", "record", "typealias"],
   "referenceKindsNote": "fun is deliberately absent, for the reason Swift's rules record for func: a bare lowercase name matched across files is almost never a call to that exact declaration, and on a large app the generic ones (invoke, build, create, get) take the top god-node slots purely because each happened to be declared once. Composables are the tempting exception - they are capitalised and behave like types - but they are declared with fun, so including them means including every other fun with them.",
   "ignoredIdentifiers": [
     "this",

package/pipeline/scripts/code-graph-rules/go.json

@@ -3,20 +3,9 @@
   "stack": "go",
   "description": "Go code-graph rules. Adds what the graph needs on top of test-gap-rules/go.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants unexported declarations too, because Phase 1 narrows scope on the whole package, not just its exported surface.",
   "comments": {
-    "line": [
-      "//"
-    ],
-    "block": [
-      [
-        "/*",
-        "*/"
-      ]
-    ],
-    "string": [
-      "`",
-      "\"",
-      "'"
-    ]
+    "line": ["//"],
+    "block": [["/*", "*/"]],
+    "string": ["`", "\"", "'"]
   },
   "importSpecifiersAreStrings": true,
   "definitionPatterns": [
@@ -47,11 +36,7 @@
       "regex": "^[ \\t]*(?:import[ \\t]+)?(?:[A-Za-z_.][A-Za-z0-9_]*[ \\t]+)?\"(?:[^\"]*/)?([A-Za-z_][A-Za-z0-9_.-]*)\"[ \\t]*$"
     }
   ],
-  "referenceKinds": [
-    "struct",
-    "interface",
-    "type"
-  ],
+  "referenceKinds": ["struct", "interface", "type"],
   "referenceKindsNote": "func is deliberately absent, for the reason the Swift, Kotlin, Node and Python rules all record: a bare name matched across files is almost never a call to that exact declaration, and Go's short-name convention (New, Run, Get, Close, Error) makes it worse than most. Functions still reach the graph through their defines edge, so they stay findable by name.",
   "ignoredIdentifiers": [
     "package",

package/pipeline/scripts/code-graph-rules/node.json

@@ -3,20 +3,9 @@
   "stack": "node",
   "description": "TypeScript + JavaScript code-graph rules. Adds what the graph needs on top of test-gap-rules/node.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants unexported declarations too, because Phase 1 narrows scope on the whole module, not just its public surface.",
   "comments": {
-    "line": [
-      "//"
-    ],
-    "block": [
-      [
-        "/*",
-        "*/"
-      ]
-    ],
-    "string": [
-      "`",
-      "\"",
-      "'"
-    ]
+    "line": ["//"],
+    "block": [["/*", "*/"]],
+    "string": ["`", "\"", "'"]
   },
   "definitionPatterns": [
     {
@@ -56,13 +45,7 @@
       "regex": "(?:\\bfrom|\\brequire\\s*\\(|\\bimport)\\s*\\(?\\s*[\"'](?:[^\"']*[\\/:])?([A-Za-z_$][A-Za-z0-9_$-]*)(?:\\.[A-Za-z0-9]+)*[\"']"
     }
   ],
-  "referenceKinds": [
-    "class",
-    "interface",
-    "type",
-    "enum",
-    "const"
-  ],
+  "referenceKinds": ["class", "interface", "type", "enum", "const"],
   "referenceKindsNote": "function is deliberately absent, for the reason Swift's rules record for func: a bare name matched across files is almost never a call to that exact declaration, and the generic ones (run, main, get, parse, handler) would take the top god-node slots purely because each happened to be declared once. Functions still reach the graph through their defines edge, so they stay findable by name. const is present but narrowed to an uppercase-initial declaration at column 0, which is what a component, a singleton or an exported table looks like; a lowercase const is a local and is not a declaration anyone references across files. Measured on this repo (126 sources): including function put `ok` at degree 52, `f` at 38, `tokens` at 15 and `arg` at 12 - local helper names that happen to be declared exactly once, so the ambiguity rule does not catch them either. Excluding it leaves a thin symbol layer, and that is the honest shape of this stack: a JavaScript module's exported unit is usually a function, so the useful graph here is the import graph between files. `graph-affected \"<file>.mjs\"` answers who imports a module, which is the question this stack actually gets asked.",
   "ignoredIdentifiers": [
     "this",

package/pipeline/scripts/feedback-send.mjs

@@ -115,7 +115,9 @@ function endpointAllowed(endpoint) {
 async function main() {
   const text = String(arg("--text", "") ?? "").trim();
   if (!text) {
-    process.stderr.write('usage: feedback-send.mjs --text "<message>" [--kind bug|idea|question]\n');
+    process.stderr.write(
+      'usage: feedback-send.mjs --text "<message>" [--kind bug|idea|question]\n',
+    );
     process.exit(2);
   }
   if (text.length > TEXT_MAX) {

package/pipeline/scripts/gate-linux.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# gate-linux.sh  -  run the ci-lite job on a real Ubuntu image, locally.
+#
+# The pre-push gate (pre-push-check.sh) is the primary one, but it runs on the
+# maintainer's macOS workstation against an installed node_modules that has
+# accumulated over months. Two things it cannot answer: does this tree work on
+# Linux, and does `npm ci` from the lockfile into an empty tree still resolve.
+# ci-lite.yml answers both, and has not executed since 2026-07-25.
+#
+# `act` runs that workflow against the same image GitHub would use, so the
+# answer comes from the workflow definition rather than from a second script
+# that would drift away from it.
+#
+# NOT part of `npm run gate` on purpose: act and Docker are not installed
+# everywhere, and a required gate that cannot run is the failure ADR-0011
+# exists to avoid. Run it before a release, or after touching install/,
+# lib/credential-store.sh, or anything path-shaped.
+#
+# Needs network inside the container: the scorecard's dependency metrics ask
+# the registry (advisories and signatures) and report an unreachable registry
+# as a failure rather than a skip, on the grounds that a supply-chain check
+# which goes green without reaching the registry is worse than no check.
+#
+# Exit codes: 0 = the job passed, 1 = the job failed, 2 = tooling missing
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT" || { echo "FAIL: can't cd to repo root" >&2; exit 2; }
+
+if ! command -v act >/dev/null 2>&1; then
+  cat >&2 <<'MSG'
+✗ act is not installed - this gate needs it to run the Ubuntu job locally.
+
+    brew install act        # macOS
+    # and a running Docker daemon (Docker Desktop, colima, orbstack)
+
+Why this is not bundled: it pulls a multi-gigabyte runner image. The rest of
+the gate chain (npm run gate) has no such dependency and stays the default.
+MSG
+  exit 2
+fi
+
+if ! docker info >/dev/null 2>&1; then
+  echo "✗ act is installed but no Docker daemon is reachable. Start Docker and retry." >&2
+  exit 2
+fi
+
+echo "→ Running ci-lite on ubuntu-22.04 via act (this pulls an image on first run)"
+echo ""
+
+if act workflow_dispatch \
+  -W .github/workflows/ci-lite.yml \
+  -P ubuntu-latest=catthehacker/ubuntu:act-22.04; then
+  echo ""
+  echo "✓ ci-lite passed on Linux"
+  exit 0
+fi
+
+echo "" >&2
+echo "✗ ci-lite failed on Linux. A pass on macOS does not cover this." >&2
+exit 1

package/pipeline/scripts/localize-commands.mjs

@@ -116,8 +116,7 @@ export function localizeCommands(dir, mode) {
 // `.split("/").pop()` never split a backslash path, so on Windows this was
 // always false - `restore` exited 0 doing nothing and /multi-agent:sync then
 // mirrored localized descriptions into the repo, the one thing it must prevent.
-const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   const args = process.argv.slice(2);
   const mode = args[0];

package/pipeline/scripts/pre-push-check.sh

@@ -3,10 +3,12 @@
 #
 # Purpose:
 #   The repo HAS workflows (test.yml, ci-lite.yml), but they have not executed
-#   since 2026-07-25: the jobs complete in ~2 seconds with zero steps recorded,
-#   which is a runner/quota block rather than a test failure. Until that is
-#   resolved, this hook is not a second opinion - it is the only thing standing
-#   between a broken commit and npm.
+#   since 2026-07-02: every attempt after that day - the last on 2026-07-25 -
+#   finished in about four seconds with zero steps recorded, which is a
+#   runner/quota block rather than a test failure. Both are now dormant by
+#   declaration too (ADR-0011: the push triggers are commented out). So this
+#   hook is not a second opinion - it is the only thing standing between a
+#   broken commit and npm.
 #
 #   It therefore runs the CANONICAL chain, `npm test`, rather than a hand-picked
 #   subset. The subset it used to run was missing eight of the eleven steps

package/pipeline/scripts/usage-report.mjs

@@ -69,8 +69,7 @@ function readJson(path) {
 
 function resolveGlobalPrefs() {
   const path =
-    process.env.MULTI_AGENT_PREFS ||
-    join(homedir(), ".claude", "multi-agent-preferences.json");
+    process.env.MULTI_AGENT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json");
   return readJson(path)?.global ?? {};
 }
 
@@ -130,9 +129,7 @@ function enabledPlugins(state) {
   ]) {
     for (const name of readEnabledPluginNames(s)) names.add(name.split("@")[0]);
   }
-  return Array.from(names)
-    .filter(Boolean)
-    .slice(0, 20);
+  return Array.from(names).filter(Boolean).slice(0, 20);
 }
 
 function integrationTags(state) {
@@ -146,8 +143,7 @@ function integrationTags(state) {
     const tool = String(call?.tool || "");
     // Server segment may contain hyphens (mcp__multi-agent-toolkit__ios_tap), so the
     // class must accept them or "multi-agent-toolkit" collapses to "dev".
-    const m =
-      tool.match(/^mcp__([a-z0-9_-]+?)__/i) || tool.match(/^mcp__([a-z0-9_-]+)/i);
+    const m = tool.match(/^mcp__([a-z0-9_-]+?)__/i) || tool.match(/^mcp__([a-z0-9_-]+)/i);
     if (m) apps.add(m[1].replace(/_/g, "-").toLowerCase());
   }
   return Array.from(apps).slice(0, 20);
@@ -345,7 +341,8 @@ function trackerSummary(state) {
   const phs = [];
   const failed = [];
   const models = new Set();
-  let startedAt = typeof tracker?.started_at === "string" && tracker.started_at ? tracker.started_at : null;
+  let startedAt =
+    typeof tracker?.started_at === "string" && tracker.started_at ? tracker.started_at : null;
   let endedAt = null;
   for (const p of list) {
     const id = p?.id != null && String(p.id) !== "" ? String(p.id) : "?";
@@ -510,9 +507,7 @@ function buildEvent(state) {
     ph: typeof state.currentPhase === "number" ? state.currentPhase : null,
     st: state.status || null,
     hr: state.haltReason || null,
-    ri: Array.isArray(state.reviewIterations)
-      ? state.reviewIterations.length
-      : 0,
+    ri: Array.isArray(state.reviewIterations) ? state.reviewIterations.length : 0,
     pr: Boolean(state.pr && (state.pr.url || state.pr.number)),
     du: durationSec(state, spend),
     tk: spend.tk,
@@ -612,10 +607,17 @@ async function main() {
 }
 
 // Windows-safe entry-point check: compare file URLs, never string-split a path.
-const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   main().catch(() => process.exit(0));
 }
 
-export { endpointAllowed, integrationTags, enabledPlugins, readEnabledPluginNames, trackerSummary, buildEvent, resolveUser };
+export {
+  endpointAllowed,
+  integrationTags,
+  enabledPlugins,
+  readEnabledPluginNames,
+  trackerSummary,
+  buildEvent,
+  resolveUser,
+};