@mmerterden/multi-agent-pipeline 15.0.0 → 15.2.0

package/install/_platform-filter.mjs

@@ -1,147 +1,22 @@
 /**
- * Platform classification + filtered copy for the external skill catalog.
+ * Stack partition + delivery manifest for the external skill catalog.
  *
- * The `--platform=ios|android|all` flag narrows `pipeline/skills/shared/external/`
- * to the requested platform. Generic skills always copy regardless of filter.
+ * The pre-v15 prefix classifier and its filtered-copy path
+ * (`classifyExternalSkill` / `copyExternalSkillsFiltered`) were removed once the
+ * routing table (`_stack-routing.mjs`) became the single source of stack
+ * affinity - `partitionExternalSkillsByPlugins` is what every installer uses.
  *
  * @module install/_platform-filter
  */
 
 import { readdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { copyDir, countFiles, ensureDir, isDryRun } from "./_common.mjs";
+import { isDryRun } from "./_common.mjs";
 import { routeSkill } from "../pipeline/scripts/_stack-routing.mjs";
 
 /** Uninstall reads this to know exactly which external skill dirs are ours to remove. */
 export const EXTERNAL_SKILLS_MANIFEST = ".external-skills-manifest.json";
 
-/**
- * Heuristic prefix lists - intentionally loose so new skills added to
- * `shared/external/` are classified by name (no manifest required). A skill
- * that doesn't match either list is treated as "generic" and copies for every
- * platform.
- */
-const IOS_PREFIXES = [
-  "swift",
-  "swiftui",
-  "ios",
-  "apple",
-  "xcode",
-  "uikit",
-  "watchkit",
-  "passkit",
-  "storekit",
-  "healthkit",
-  "activitykit",
-  "weatherkit",
-  "pencilkit",
-  "callkit",
-  "eventkit",
-  "homekit",
-  "mapkit",
-  "musickit",
-  "permissionkit",
-  "speech",
-  "metrickit",
-  "widgetkit",
-  "vision",
-  "app-store",
-  "app-clips",
-  "app-intents",
-  "app-tracking",
-  "hig-",
-  "coreml",
-  "core-nfc",
-  "core-bluetooth",
-  "core-motion",
-  "cloudkit",
-  "live-activities",
-  "realitykit",
-  "tipkit",
-  "alarmkit",
-  "energykit",
-  "natural-language",
-  "authentication",
-  "background-processing",
-  "contacts",
-  "device-integrity",
-  "debugging-instruments",
-  "macos-",
-  "ios-",
-  "photos-camera",
-  "push-notifications",
-  "shareplay",
-  "apple-on-device",
-  "swiftdata",
-  "swift-",
-];
-
-const ANDROID_PREFIXES = [
-  "android",
-  "kotlin",
-  "jetpack",
-  "compose",
-  "room",
-  "retrofit",
-  "gradle",
-  "material",
-  "play-store",
-];
-
-/**
- * Classify an external skill directory name into its platform affinity.
- *
- * @param {string} skillName - directory name under `shared/external/`
- * @returns {"ios" | "android" | "generic"}
- */
-export function classifyExternalSkill(skillName) {
-  const lower = skillName.toLowerCase();
-  if (IOS_PREFIXES.some((p) => lower.startsWith(p))) return "ios";
-  if (ANDROID_PREFIXES.some((p) => lower.startsWith(p))) return "android";
-  return "generic";
-}
-
-/**
- * Platform-filtered copy of `shared/external/` skills.
- *
- * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
- * @param {string} dest - absolute path to target install dir
- * @param {{ platformFlag: "ios"|"android"|"all", useSymlinks?: boolean }} opts
- * @returns {{ copied: number, skipped: number }}
- */
-export function copyExternalSkillsFiltered(externalSrc, dest, opts) {
-  const { platformFlag, useSymlinks = false } = opts;
-  const allNames = readdirSync(externalSrc, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name);
-
-  if (platformFlag === "all") {
-    copyDir(externalSrc, dest, { useSymlinks });
-    writeExternalSkillsManifest(dest, allNames);
-    return { copied: countFiles(externalSrc), skipped: 0 };
-  }
-
-  ensureDir(dest);
-  let copied = 0;
-  let skipped = 0;
-  const delivered = [];
-  for (const name of allNames) {
-    const classification = classifyExternalSkill(name);
-    const shouldCopy = classification === "generic" || classification === platformFlag;
-    const src = join(externalSrc, name);
-    const dst = join(dest, name);
-    if (shouldCopy) {
-      copyDir(src, dst, { useSymlinks });
-      copied += countFiles(src);
-      delivered.push(name);
-    } else {
-      skipped += 1;
-    }
-  }
-  writeExternalSkillsManifest(dest, delivered);
-  return { copied, skipped };
-}
-
 /**
  * Enabled-stack partition of the external skill catalog.
  *

package/install/_plugin-skills.mjs

@@ -33,10 +33,10 @@ export const PLUGIN_SKILLS_MANIFEST = ".plugin-skills-manifest.json";
 import { copyDir, countFiles, ensureDir, ensureRealDir, isDryRun, wipeDir } from "./_common.mjs";
 
 /** Subtrees a plugin authors itself. `knowledge/` is generated, so it is excluded. */
-export const AUTHORED_GROUPS = Object.freeze(["index", "reference", "workflow", "tools"]);
+const AUTHORED_GROUPS = Object.freeze(["index", "reference", "workflow", "tools"]);
 
 /** Stack plugins, and the platform each belongs to. */
-export const STACK_PLUGINS = Object.freeze([
+const STACK_PLUGINS = Object.freeze([
   { name: "ai-ios-toolkit", platform: "ios" },
   { name: "ai-android-toolkit", platform: "android" },
   { name: "ai-frontend-toolkit", platform: "all" },
@@ -71,7 +71,7 @@ function semverCompare(a, b) {
  * @param {string} pluginName
  * @returns {{path: string, source: string}|null}
  */
-export function resolvePluginSkills(home, pluginName) {
+function resolvePluginSkills(home, pluginName) {
   const checkout = join(home, "multi-agent-plugins", "plugins", pluginName, "skills");
   if (existsSync(checkout)) return { path: checkout, source: "local checkout" };
 
@@ -104,17 +104,22 @@ export function resolvePluginSkills(home, pluginName) {
  * A flat copy of all of them is last-write-wins, so an iOS repo could end up running
  * the Android `create-component`.
  *
- * So the enabled list in Claude Code's settings is the source of truth; the
- * `--platform` flag is only the fallback for a machine that has no Claude Code
- * settings to read.
+ * So the enabled list in Claude Code's settings is the source of truth, and it is
+ * read where `/multi-agent:stack` writes it: the invoking repo's
+ * `.claude/settings.json` first, the user-global `~/.claude/settings.json` second.
+ * The `--platform` flag is only the fallback for a machine with neither.
  *
  * @param {string} home
  * @param {"ios"|"android"|"all"} platformFlag
  * @returns {{names: string[], source: string}}
  */
 export function pluginsToDeliver(home, platformFlag) {
-  const settingsPath = join(home, ".claude", "settings.json");
-  if (existsSync(settingsPath)) {
+  const candidates = [
+    { path: join(process.cwd(), ".claude", "settings.json"), label: "./.claude/settings.json" },
+    { path: join(home, ".claude", "settings.json"), label: "~/.claude/settings.json" },
+  ];
+  for (const { path: settingsPath, label } of candidates) {
+    if (!existsSync(settingsPath)) continue;
     try {
       const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
       const enabled = Object.entries(settings.enabledPlugins || {})
@@ -127,10 +132,10 @@ export function pluginsToDeliver(home, platformFlag) {
         // collision the first delivery wins, and the stack-specific version is the
         // one the repo actually wants.
         const ordered = STACK_PLUGINS.map((p) => p.name).filter((n) => enabled.includes(n));
-        return { names: ordered, source: "enabledPlugins in ~/.claude/settings.json" };
+        return { names: ordered, source: `enabledPlugins in ${label}` };
       }
     } catch {
-      /* unreadable settings fall through to the platform default */
+      /* unreadable settings fall through to the next candidate */
     }
   }
   const names = STACK_PLUGINS.filter(
@@ -282,27 +287,11 @@ export function installAuthoredPluginSkills(opts) {
   };
 }
 
-/**
- * Names already present in a flat skills directory, so a second delivery pass does
- * not overwrite what the pipeline itself installed.
- *
- * @param {string} dir
- * @returns {Set<string>}
- */
-export function existingSkillNames(dir) {
-  if (!existsSync(dir)) return new Set();
-  return new Set(
-    readdirSync(dir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name),
-  );
-}
-
 /**
  * Skill names the PIPELINE owns, derived from its source tree.
  *
- * This is what `skipNames` should be. Callers used to pass
- * `existingSkillNames(dest)` - a snapshot of whatever was already installed - which
+ * This is what `skipNames` should be. Callers used to pass a snapshot of
+ * whatever was already installed (a now-deleted `existingSkillNames(dest)`) - which
  * did protect pipeline skills from being shadowed by a plugin, but also meant a
  * plugin skill was copied exactly once and then frozen: on the second install its
  * own name was "already there", so it was skipped, forever. A stale plugin skill

package/install/claude.mjs

@@ -25,9 +25,11 @@ import {
   copyFile,
   copySkillsIndex,
   countFiles,
+  dirsIdentical,
   ensureDir,
   ensureRealDir,
   isDryRun,
+  isLocalOnlySkill,
   pruneAbandonedTrees,
   pruneLegacyMultiAgentSkills,
   pruneOrphanSkillFiles,
@@ -63,10 +65,11 @@ export const PIPELINE_LOCAL_SKILLS = ["apple-archive-compliance", "google-play-c
  *   indexOnly: boolean,
  *   useSymlinks: boolean,
  *   platformFlag: "ios"|"android"|"all",
+ *   pruneExternal?: boolean,
  * }} ctx
  */
 export function installClaude(ctx) {
-  const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag } = ctx;
+  const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag, pruneExternal } = ctx;
 
   const CLAUDE_COMMANDS = join(home, ".claude", "commands");
   const CLAUDE_AGENTS = join(home, ".claude", "agents");
@@ -94,7 +97,7 @@ export function installClaude(ctx) {
   installSchemas(pipelineSrc, CLAUDE_SCHEMAS, useSymlinks);
   installLib(pipelineSrc, CLAUDE_LIB, useSymlinks);
   runPreDeployScans(pipelineSrc);
-  installSkills({ pipelineSrc, dest: CLAUDE_SKILLS, indexOnly, useSymlinks, platformFlag });
+  installSkills({ pipelineSrc, dest: CLAUDE_SKILLS, indexOnly, useSymlinks, platformFlag, pruneExternal });
   ensureClaudeMd(home, pipelineSrc);
   ensurePreferences(PREFS_PATH, pipelineSrc);
   configureSettings(home);
@@ -355,7 +358,7 @@ function runPreDeployScans(pipelineSrc) {
 }
 
 function installSkills(opts) {
-  const { pipelineSrc, dest, indexOnly, useSymlinks } = opts;
+  const { pipelineSrc, dest, indexOnly, useSymlinks, pruneExternal } = opts;
   console.log("  [Claude Code] Installing skills...");
 
   // Same symlink guard as the other owned trees: never prune or copy through
@@ -403,9 +406,7 @@ function installSkills(opts) {
 
   // Migration prune: an older install delivered the full external catalog here.
   // Its manifest names exactly what was delivered, so removal is manifest-scoped -
-  // user-authored skills in the same directory are untouched. Without a manifest
-  // nothing is guessed; the stale copy then outlives this install and the user
-  // can clean it via uninstall --claude.
+  // user-authored skills in the same directory are untouched.
   const migrated = pruneManifestDeliveredSkills(dest);
   if (migrated > 0) {
     console.log(
@@ -413,6 +414,16 @@ function installSkills(opts) {
     );
   }
 
+  // Pre-manifest installs (<= v14.x) never wrote that manifest, so the branch
+  // above cannot fire for them and the full 151-dir catalog would outlive every
+  // upgrade. For those, prune by proof instead of by name: a dir byte-identical
+  // to the shipped catalog contains nothing of the user's and goes now; a dir
+  // that differs is kept unless --prune-external explicitly opts in (and even
+  // then a `local-only: true` SKILL.md keeps it).
+  migratePreManifestExternalSkills(dest, join(pipelineSrc, "skills", "shared", "external"), {
+    pruneExternal: Boolean(pruneExternal),
+  });
+
   // Figma component skills moved to the ai-<platform>-toolkit marketplace
   // plugin and are no longer bundled here. Prune any stale copies left by a
   // pre-migration install so the installed tree stays consistent.
@@ -482,6 +493,10 @@ function pruneManifestDeliveredSkills(dest) {
   try {
     const names = JSON.parse(readFileSync(manifestPath, "utf-8"));
     for (const name of Array.isArray(names) ? names : []) {
+      // The manifest is untrusted input feeding a recursive rmSync: a name
+      // carrying a path separator or leading dot would escape the skills dir
+      // (join normalizes "../x"), so only plain directory names pass.
+      if (typeof name !== "string" || /[/\\]/.test(name) || name.startsWith(".")) continue;
       // The two local compliance catalogs are never external-delivered, but a
       // corrupted manifest must not be able to take them out.
       if (PIPELINE_LOCAL_SKILLS.includes(name)) continue;
@@ -510,6 +525,96 @@ function pruneManifestDeliveredSkills(dest) {
   return removed;
 }
 
+/**
+ * Migration for pre-manifest installs (<= v14.x): the external catalog was
+ * copied here with no delivery manifest, so ours and the user's are told apart
+ * by content, not by name. Byte-identical to the shipped catalog = provably
+ * ours, removed. Different = kept, reported, and removable only via the
+ * explicit `--prune-external` flag (which still honors `local-only: true`).
+ *
+ * @param {string} dest - the installed skills directory
+ * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
+ * @param {{ pruneExternal: boolean }} opts
+ */
+function migratePreManifestExternalSkills(dest, externalSrc, opts) {
+  if (!existsSync(externalSrc) || !existsSync(dest)) return;
+  const { pruneExternal } = opts;
+  let identical = 0;
+  let flagged = 0;
+  const leftover = [];
+  for (const entry of readdirSync(externalSrc, { withFileTypes: true })) {
+    const name = entry.name;
+    if (PIPELINE_LOCAL_SKILLS.includes(name)) continue;
+    const stale = join(dest, name);
+    if (!existsSync(stale)) continue;
+
+    // NOTICE-*.md files rode along with the catalog as plain files.
+    if (!entry.isDirectory()) {
+      if (!/^NOTICE-.*\.md$/.test(name)) continue;
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune stale ${name} (pre-manifest catalog copy)`);
+        continue;
+      }
+      try {
+        rmSync(stale, { force: true });
+        identical++;
+      } catch {
+        /* non-fatal */
+      }
+      continue;
+    }
+
+    let provablyOurs;
+    try {
+      provablyOurs = dirsIdentical(join(externalSrc, name), stale);
+    } catch {
+      provablyOurs = false;
+    }
+    if (provablyOurs) {
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune ${name}/ (identical to shipped catalog)`);
+        identical++;
+        continue;
+      }
+      try {
+        rmSync(stale, { recursive: true, force: true });
+        identical++;
+      } catch {
+        /* non-fatal */
+      }
+    } else if (pruneExternal && !isLocalOnlySkill(stale)) {
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune ${name}/ (--prune-external)`);
+        flagged++;
+        continue;
+      }
+      try {
+        rmSync(stale, { recursive: true, force: true });
+        flagged++;
+      } catch {
+        /* non-fatal */
+      }
+    } else {
+      leftover.push(name);
+    }
+  }
+  if (identical > 0) {
+    console.log(
+      `    -> migration: pruned ${identical} pre-manifest catalog entr(ies) identical to the shipped catalog (now plugin-only)`,
+    );
+  }
+  if (flagged > 0) {
+    console.log(`    -> --prune-external: removed ${flagged} catalog-named skill dir(s) that had local differences`);
+  }
+  if (leftover.length > 0) {
+    console.log(
+      `    note: ${leftover.length} skill dir(s) share catalog names but differ from the shipped catalog - kept ` +
+        `(cannot tell an older delivery from user edits). Remove them too with: node install.js --claude --prune-external`,
+    );
+  }
+}
+
+
 function ensureClaudeMd(home, pipelineSrc) {
   console.log("  [Claude Code] Checking CLAUDE.md template...");
   const CLAUDE_MD = join(home, ".claude", "CLAUDE.md");

package/install/codex.mjs

@@ -52,9 +52,6 @@ export const AGENTS_MD_START_MARKER = "# Multi-Agent Development Pipeline";
 /** Explicit end marker written after the pipeline section. */
 export const AGENTS_MD_END_MARKER = "<!-- multi-agent-pipeline:codex-instructions:end -->";
 
-/** Re-exported for the uninstaller and the Codex install smoke. */
-export { MCP_SERVER_NAME } from "./_mcp-register.mjs";
-
 /**
  * `$HOME/.claude/...` path rewrites applied to every file installed into the
  * Codex tree.

package/install/copilot.mjs

@@ -16,6 +16,7 @@ import {
   copyFile,
   copySkillsIndex,
   countFiles,
+  dirsIdentical,
   ensureDir,
   ensureRealDir,
   isDryRun,
@@ -25,6 +26,7 @@ import {
   writeFile,
 } from "./_common.mjs";
 import {
+  EXTERNAL_SKILLS_MANIFEST,
   partitionExternalSkillsByPlugins,
   writeExternalSkillsManifest,
 } from "./_platform-filter.mjs";
@@ -372,6 +374,15 @@ function installSkills(opts) {
     const { names: enabled, source: selectionSource } = pluginsToDeliver(home, platformFlag);
     const { keep, skipped } = partitionExternalSkillsByPlugins(sharedExternalSrc, enabled);
     ensureDir(dest);
+    // Read the PREVIOUS delivery manifest before this install overwrites it -
+    // it is what makes the stale prune below manifest-scoped.
+    let prevDelivered = null;
+    try {
+      const parsed = JSON.parse(readFileSync(join(dest, EXTERNAL_SKILLS_MANIFEST), "utf-8"));
+      if (Array.isArray(parsed)) prevDelivered = new Set(parsed.filter((n) => typeof n === "string"));
+    } catch {
+      prevDelivered = null;
+    }
     for (const name of keep) {
       const src = join(sharedExternalSrc, name);
       const dst = join(dest, name);
@@ -380,10 +391,29 @@ function installSkills(opts) {
       copilotSkillCount += countFiles(src);
     }
     // Stale prune: a skill delivered by a previous, wider stack selection must
-    // leave when the selection narrows, or the old stack lingers forever.
+    // leave when the selection narrows, or the old stack lingers forever. Scope:
+    // only dirs the previous manifest names (delivered by us), or - on a
+    // pre-manifest install - dirs byte-identical to the shipped catalog. A
+    // user-authored dir that happens to share a catalog name matches neither
+    // and is never touched.
+    let keptForeign = 0;
     for (const name of skipped) {
       const stale = join(dest, name);
       if (!existsSync(stale) || isDryRun()) continue;
+      let ours;
+      if (prevDelivered) {
+        ours = prevDelivered.has(name);
+      } else {
+        try {
+          ours = dirsIdentical(join(sharedExternalSrc, name), stale);
+        } catch {
+          ours = false;
+        }
+      }
+      if (!ours) {
+        keptForeign++;
+        continue;
+      }
       try {
         rmSync(stale, { recursive: true, force: true });
       } catch {
@@ -392,6 +422,11 @@ function installSkills(opts) {
     }
     writeExternalSkillsManifest(dest, keep);
     console.log(`    -> stack filter (${selectionSource}): ${keep.length} kept, ${skipped.length} skipped`);
+    if (keptForeign > 0) {
+      console.log(
+        `    note: ${keptForeign} skipped-stack dir(s) kept - not delivered by this pipeline (no manifest entry, differs from catalog)`,
+      );
+    }
   }
 
   // The pre-migration figma-* skill copies are gone; the plugin owns component work

package/install/index.mjs

@@ -45,7 +45,7 @@ export async function runInstall(argv) {
   //   `multi-agent-pipeline install --all` (via bin, argv[2]="install")
   const flags = argv.slice(2).filter((a) => a !== "install");
 
-  const KNOWN_FLAGS = [...TOOL_FLAGS, "--all", "--link", "--index-only", "--dry-run"];
+  const KNOWN_FLAGS = [...TOOL_FLAGS, "--all", "--link", "--index-only", "--dry-run", "--prune-external"];
   const KNOWN_PREFIXES = ["--target=", "--platform="];
   const unknown = flags.filter(
     (f) =>
@@ -74,6 +74,7 @@ export async function runInstall(argv) {
 
   const useSymlinks = flags.includes("--link");
   const indexOnly = flags.includes("--index-only");
+  const pruneExternal = flags.includes("--prune-external");
   const platformFlag = parsePlatformFlag(flags);
 
   const installerCtx = {
@@ -82,6 +83,7 @@ export async function runInstall(argv) {
     indexOnly,
     useSymlinks,
     platformFlag,
+    pruneExternal,
   };
 
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.0.0",
+  "version": "15.2.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -68,11 +68,11 @@
     "install.js",
     "install/**/*",
     "pipeline/**/*",
-    "pipeline/scripts/**/*",
     "docs/**/*",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
+    "SECURITY.md",
     "!pipeline/scripts/smoke-figma-config-schema.sh",
     "!pipeline/scripts/smoke-personal-data.sh",
     "!pipeline/scripts/validate-prefs.mjs",

package/pipeline/commands/multi-agent/refactor/SKILL.md

@@ -18,10 +18,11 @@ Deep-analyses the current project, extracts the global best-practices worth adop
 Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
 Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion dev-toolkit repo -> plan band E
+Step 0d: RUN-ERRORS      Read the local run-error ledger, rank recurring failures -> plan band F
 Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
 Step 3:  SCORE           Each category /10, overall /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit) + F (run-errors)
 Step 5:  ASK             "Start the work?"  -  wait for user approval
 Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
 Step 7:  VERIFY          Confirm every test + lint passes
@@ -34,6 +35,7 @@ Plan bands (all five feed the single Step 4 table):
 - **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
 - **D - Drift**: upstream updates to skills we derived from an external source.
 - **E - Dev-toolkit**: current-practice gaps in the companion dev-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
+- **F - Run-errors**: recurring real failures the pipeline actually hit across past runs, read from the local run-error ledger. These are lived evidence, not speculation - a failure that recurs across users or tasks is a prioritized improvement area.
 
 ## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
@@ -178,6 +180,39 @@ Rules for this band:
 - A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
 - If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
 
+## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
+
+Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger:
+
+```bash
+LEDGER="$HOME/.claude/logs/multi-agent/errors-ledger.jsonl"
+[ -f "$LEDGER" ] || echo "no run-error ledger yet - skip band F"
+```
+
+Each line is one run: `{ t, id, u, c, rp, ph, v, errs[] }`. The `errs[]` entries are cause tags (`<phase>:<cause>` halt reasons, `phase-<id>-failed`, `run-failed`).
+
+1. Read the ledger (best-effort; a missing or unreadable file means skip band F, not a failure).
+2. Group by error tag. For each tag compute: occurrences, distinct users affected, distinct repos, the phase it usually strikes, first + last seen, and which pipeline versions it spans (a tag that persists across versions is unfixed; one that stopped at a version is already resolved  -  do not re-raise it).
+3. Rank by `occurrences x users-affected`. A failure that recurs across users or tasks is lived evidence, not a hypothesis  -  it outranks a speculative improvement.
+4. For each surviving tag, trace it to the phase doc / script that emits that cause and propose the concrete fix.
+
+This band mirrors the admin dashboard's "Gelişim alanları" panel, but reads the local ledger so it needs no auth and works offline. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal.
+
+Output (plan band F):
+
+```
+| # | Error tag | Occurrences | Users | Usual phase | Versions | Root cause (file) | Fix | In plan? |
+|---|-----------|-------------|-------|-------------|----------|-------------------|-----|----------|
+| 1 | 4:reviewer-json-invalid | 12 | 3 | 4 | 14.x-15.x | reviewer prompt lets prose leak | tighten schema instruction in phase-4-review.md | Yes (P0) |
+| 2 | phase-3-failed | 5 | 2 | 3 | 15.0.x | build step misses a stack toolchain | add preflight in phase-3-dev.md | Yes (P1) |
+```
+
+Rules for this band:
+
+- The ledger is evidence of the past, not a spec. A tag that stopped recurring after a version bump is resolved  -  report it as resolved, do not add a plan item.
+- Never quote a user's identity as blame. The `u` field is for counting distinct affected users, not for naming anyone in the plan.
+- If the ledger is empty or absent, skip band F silently  -  it is additive signal, never a gate.
+
 ## Step 1: SCAN
 
 ```

package/pipeline/commands/multi-agent/scan/SKILL.md

@@ -66,7 +66,7 @@ Known legitimate domains are embedded in the scanner (github, anthropic, figma,
 
 ## Smoke  -  self-verification
 
-`pipeline/scripts/smoke-skill-scan.sh` confirms the scanner triggers on positive fixtures for every severity and produces no false positives on the real tree. The smoke must be 13/13 green before a team rollout.
+`pipeline/scripts/smoke-skill-scan.sh` confirms the scanner triggers on positive fixtures for every severity and produces no false positives on the real tree. This is a maintainer-repo gate (smoke scripts are excluded from the npm package): it runs from a pipeline checkout and in CI, where it must be 13/13 green before a team rollout.
 
 ## Integration points
 

package/pipeline/commands/multi-agent/stack/SKILL.md

@@ -47,7 +47,8 @@ Multiple args union their plugin sets: `ios backend` → common + iOS + backend.
    - `question` (in `outputLanguage`): which stacks should be active in this repo, noting the currently enabled ones
    - `header`: "Stacks" (English, UI contract)
    - `options` (4): `ios` / `android` / `frontend (web)` / `backend`, each `description` (in `outputLanguage`) naming the plugin it enables and marking the ones already enabled with "(currently on)" / "(şu an açık)"
-   - Empty selection or cancel → **status mode**: print the currently enabled `@multi-agent-plugins` plugins and exit without modifying anything.
+   - Map each selected label back to its canonical arg before step 2: the token before any parenthesis (`frontend (web)` → `frontend`).
+   - Empty selection or cancel → **status mode**: print the currently enabled `@multi-agent-plugins` plugins and exit without modifying anything. Status mode never runs the Implementation block below - that block is enable-mode only.
 2. **Arg(s) present → enable mode.** Accept multiple space-separated stacks. Resolve each through the alias table (`web`→`frontend`, `mobile`→`ios android`, `fullstack`→`frontend backend`, `all`→every stack), union the plugin sets, then write the **current repo's** `.claude/settings.json`.
 3. **Write rules:**
    - every plugin in the union is set to `true`
@@ -75,17 +76,26 @@ ANDROID="ai-android-toolkit@${MP}"
 FRONTEND="ai-frontend-toolkit@${MP}"
 BACKEND="ai-backend-toolkit@${MP}"
 
+# Enable-mode only: with zero args the write rules below would set every stack
+# toolkit to false (nothing but $COMMON is in $ON), silently wiping the repo's
+# selection. No args belongs to the picker / status path (Behaviour step 1).
+if [ "$#" -eq 0 ]; then
+  echo "No stack given - nothing changed. Pass stacks (ios backend ...) or use the picker."
+  exit 0
+fi
+
 # resolve every arg through the alias table, union the ON set
 ON="$COMMON"
 for ARG in "$@"; do
   case "$ARG" in
-    ios)            ON="$ON $IOS" ;;
-    android)        ON="$ON $ANDROID" ;;
-    frontend|web)   ON="$ON $FRONTEND" ;;
-    backend)        ON="$ON $BACKEND" ;;
-    mobile)         ON="$ON $IOS $ANDROID" ;;
-    fullstack)      ON="$ON $FRONTEND $BACKEND" ;;
-    all)            ON="$ON $IOS $ANDROID $FRONTEND $BACKEND" ;;
+    ios)              ON="$ON $IOS" ;;
+    android)          ON="$ON $ANDROID" ;;
+    frontend|web)     ON="$ON $FRONTEND" ;;
+    "frontend (web)") ON="$ON $FRONTEND" ;;
+    backend)          ON="$ON $BACKEND" ;;
+    mobile)           ON="$ON $IOS $ANDROID" ;;
+    fullstack)        ON="$ON $FRONTEND $BACKEND" ;;
+    all)              ON="$ON $IOS $ANDROID $FRONTEND $BACKEND" ;;
     *) echo "Unknown stack '$ARG'. One of: ios android mobile backend frontend web fullstack all"; exit 1 ;;
   esac
 done