@mmerterden/multi-agent-pipeline 12.2.0 → 12.4.0

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,14 +6,14 @@
 
 ---
 
-## 1. Command Inventory (38 commands)
+## 1. Command Inventory (41 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 Categories:
@@ -25,6 +25,7 @@ Categories:
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
+- **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 

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

@@ -49,6 +49,24 @@
       "default": "v3",
       "description": "Template version emitted. v3 is the platform-agnostic + Pass B render template (Locked 22)."
     },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Coverage opt-ins captured at Phase 0 Step 5a. Absent = defaults (no UI tests, basic accessibility).",
+      "properties": {
+        "uiTests": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, Section 15.6 renders UI test scenarios (XCUITest / Compose UI test)."
+        },
+        "a11yDepth": {
+          "type": "string",
+          "enum": ["basic", "full"],
+          "default": "basic",
+          "description": "basic = Section 16.1 checklist only; full = also render the 16.2 VoiceOver/TalkBack walkthrough."
+        }
+      }
+    },
     "evidenceDigest": {
       "type": ["string", "null"],
       "pattern": "^sha256:[0-9a-f]{64}$",
@@ -110,6 +128,8 @@
               "url": { "type": "string", "format": "uri" },
               "fileKey": { "type": ["string", "null"] },
               "nodeId": { "type": ["string", "null"] },
+              "screenshotUrl": { "type": ["string", "null"], "description": "Local PNG path or signed render URL for this node." },
+              "tier": { "type": ["integer", "null"], "enum": [1, 2, 3, null], "description": "Figma access tier used to capture this record (mirrors state.figmaAccess.tier)." },
               "frames": {
                 "type": "array",
                 "items": {
@@ -134,6 +154,64 @@
                     "repoPath": { "type": ["string", "null"] }
                   }
                 }
+              },
+              "codeConnectSnippets": {
+                "type": "array",
+                "description": "Verbatim CodeConnectSnippet blocks captured on Tier 1 (component name + modifier chain).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "nodeId": { "type": ["string", "null"] },
+                    "component": { "type": "string" },
+                    "snippet": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "tokens": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "name": { "type": "string" },
+                    "value": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "textLayers": {
+                "type": "array",
+                "description": "Visible text-layer content. Treated as placeholder copy when an annotation exists for the same node (annotation wins).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "nodeId": { "type": ["string", "null"] },
+                    "name": { "type": ["string", "null"] },
+                    "text": { "type": "string" }
+                  }
+                }
+              },
+              "annotations": {
+                "type": "array",
+                "description": "Dev Mode annotations captured as authoritative copy ground truth (Phase 1 annotation ingestion). Empty unless annotations.enabled in the project figma-config.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["nodeId", "mode"],
+                  "properties": {
+                    "nodeId": { "type": "string" },
+                    "name": { "type": ["string", "null"] },
+                    "designText": { "type": ["string", "null"], "description": "The visible-layer text at this node (often a placeholder)." },
+                    "raw": { "type": ["string", "null"], "description": "The raw annotation label/labelMarkdown before parsing." },
+                    "parsed": {
+                      "type": "object",
+                      "description": "Parsed copy keyed by language code (lowercased), e.g. { tr, en }.",
+                      "additionalProperties": { "type": "string" }
+                    },
+                    "mode": { "type": "string", "enum": ["prefixed", "two-line", "single", "empty"] }
+                  }
+                }
               }
             }
           }

package/pipeline/schemas/figma-project-config.schema.json

@@ -50,6 +50,55 @@
         }
       }
     },
+    "annotations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Figma Dev Mode annotation ingestion. When enabled, /multi-agent:analysis treats annotations as the authoritative copy for a node (the visible text layer is a placeholder). Absent or disabled = current behavior (visible text layers only).",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "langPrefixes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["TR", "EN"],
+          "description": "Ordered language-code prefixes the annotation parser recognizes, e.g. [\"TR\",\"EN\"]. A `TR: ...\\nEN: ...` label parses by prefix; a two-line label with no prefix maps line 1 -> langPrefixes[0], line 2 -> langPrefixes[1]; a single line -> langPrefixes[0]."
+        },
+        "devModeCategory": {
+          "type": ["string", "null"],
+          "description": "Optional Dev Mode annotation category to filter on (e.g. a copy/UX-writing category). Null = accept all annotations on the node."
+        }
+      }
+    },
+    "localization": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How this project owns localization. Drives Section 10 of /multi-agent:analysis. Default `in-repo` keeps the historical hand-filled per-locale grid; `externally-owned` defers per-locale values to an authoring system (the analysis names key + status + copy source + base value only).",
+      "properties": {
+        "ownership": {
+          "type": "string",
+          "enum": ["in-repo", "externally-owned"],
+          "default": "in-repo"
+        },
+        "authoringPipeline": {
+          "type": ["string", "null"],
+          "description": "Human-readable reference to the owning localization system when ownership = externally-owned (e.g. a workflow or resource-bot name). Rendered as the Ownership column value; never a secret."
+        },
+        "locales": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Supported locale codes for this project (e.g. [\"tr\",\"en\",\"ar\",\"de\",\"es\",\"fr\",\"it\",\"ru\"]). Overrides the built-in default locale set used by Section 10.",
+          "minItems": 1
+        },
+        "baseLanguage": {
+          "type": "string",
+          "default": "en",
+          "description": "Source/base language code. A key missing its base-language value is a defect (renders the raw key at runtime)."
+        },
+        "keyPattern": {
+          "type": ["string", "null"],
+          "description": "Key naming convention hint, e.g. `Namespace.Case`. Documentation only; not enforced."
+        }
+      }
+    },
     "github": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/migrations/prefs-2.3.0-to-2.4.0.mjs

@@ -0,0 +1,32 @@
+/**
+ * prefs-2.3.0-to-2.4.0.mjs  -  preference schema upgrade 2.3.0 -> 2.4.0
+ *
+ * Adds the user-defined routine registry:
+ *   - global.routines  (v2.4.0)  -  array of {name, description, createdAt,
+ *                                   source, trigger?} indexing local-only
+ *                                   /multi-agent:<name> commands saved via
+ *                                   /multi-agent:save. Never synced (personal).
+ *
+ * Defaults to an empty array. Existing v2.3.0 prefs validate against the
+ * v2.4.0 schema without it, but the migrator initializes it so the routine
+ * commands can read/append without null-guards.
+ *
+ * Idempotent: safe on already-2.4.0 input. Non-destructive: preserves any
+ * user-saved routines.
+ *
+ * @param {object} data  -  parsed JSON content of the preferences file
+ * @returns {object}     -  same data with schemaVersion = "2.4.0"
+ */
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.4.0";
+
+  if (!out.global) out.global = {};
+
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+  }
+
+  return out;
+}

package/pipeline/schemas/prefs.schema.json

@@ -17,7 +17,8 @@
         "2.0.0",
         "2.1.0",
         "2.2.0",
-        "2.3.0"
+        "2.3.0",
+        "2.4.0"
       ],
       "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump."
     },
@@ -273,6 +274,40 @@
             "maxItems": 10
           }
         },
+        "routines": {
+          "type": "array",
+          "description": "v2.4.0+. User-defined routines saved via /multi-agent:save. Each entry indexes a local-only /multi-agent:<name> command dir under ~/.claude/commands/multi-agent/. Never synced (personal). Managed by routine-registry.mjs.",
+          "maxItems": 100,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "description"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "maxLength": 40,
+                "description": "Routine command name; invocable as /multi-agent:<name>."
+              },
+              "description": {
+                "type": "string",
+                "description": "One-line summary shown by /multi-agent:routines and :help."
+              },
+              "createdAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "source": {
+                "type": "string",
+                "description": "Where the routine came from, e.g. a CLAUDE.md section name or 'user'."
+              },
+              "trigger": {
+                "type": ["string", "null"],
+                "description": "Optional natural-language trigger phrase the routine captures."
+              }
+            }
+          }
+        },
         "recentGroups": {
           "type": "array",
           "description": "v2.1.0+. LRU of multi-repo selection groups. Each group is a set of repo paths chosen together for multi-repo tasks. Max 10.",
@@ -1258,6 +1293,28 @@
             "figmaConfigPath": {
               "type": "string",
               "description": "Path to per-project figma-config.json (for Figma pipeline projects)."
+            },
+            "standardsFile": {
+              "type": "string",
+              "description": "Filename (or absolute/tilde path) of the canonical home-dir Standards reference for this project, used by /multi-agent:analysis Q5 auto-detect (e.g. ~/<project>-Standards.md)."
+            },
+            "editableRelatedRepos": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Extra writable repos to offer in the dev-context picker beyond auto-detected submodules (iOS/Android/Backend)."
+            },
+            "frontendRepos": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Frontend repos for this project, used by /multi-agent:analysis Step 4 (Frontend is rarely in the iOS/Android submodule tree)."
+            },
+            "frontendRoots": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Whitelist source roots for the Frontend repo-evidence scan (overrides the default src/ app/ components/ features/ lib/)."
             }
           }
         }

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,19 +1,19 @@
 .claude/.pipeline-version	1
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	44
-.claude/lib	26
+.claude/commands	47
+.claude/lib	27
 .claude/multi-agent-preferences.json	1
 .claude/multi-agent-refs	51
 .claude/rules	12
-.claude/schemas	23
-.claude/scripts	193
+.claude/schemas	24
+.claude/scripts	197
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
-.copilot/lib	26
-.copilot/schemas	23
-.copilot/scripts	193
-.copilot/skills	467
+.copilot/lib	27
+.copilot/schemas	24
+.copilot/scripts	197
+.copilot/skills	470

package/pipeline/scripts/migrate-prefs.mjs

@@ -18,7 +18,7 @@ const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences
 
 // Single source of truth for the migration target version. Referenced by the
 // migrate() bump chain AND every user-facing message, so they cannot drift.
-const TARGET_VERSION = "2.3.0";
+const TARGET_VERSION = "2.4.0";
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -164,6 +164,9 @@ function migrate(prefs) {
   const TARGET = TARGET_VERSION;
   if (out.schemaVersion === TARGET) {
     // already on target  -  skip version bump, but still run sub-migrations below
+  } else if (out.schemaVersion === "2.3.0") {
+    out.schemaVersion = TARGET;
+    changes.push(`schemaVersion: 2.3.0 → ${TARGET}`);
   } else if (out.schemaVersion === "2.2.0") {
     out.schemaVersion = TARGET;
     changes.push(`schemaVersion: 2.2.0 → ${TARGET}`);
@@ -241,6 +244,10 @@ function migrate(prefs) {
     out.global.accounts = [];
     changes.push("added empty accounts (v7.4.0 per-account host overrides)");
   }
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+    changes.push("added empty routines (v2.4.0 user-defined /multi-agent:save routines)");
+  }
   if (!out.global.serviceStatus) {
     out.global.serviceStatus = {};
     changes.push("added empty serviceStatus");

package/pipeline/scripts/routine-registry.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// routine-registry.mjs  -  backend for the user-defined routine commands
+// (/multi-agent:save, :routines, :forget).
+//
+// A "routine" is a saved, reusable procedure the user binds to its own
+// /multi-agent:<name> slash command. Each routine is TWO artifacts:
+//   1. a local-only command dir  ~/.claude/commands/multi-agent/<name>/SKILL.md
+//      (frontmatter `local-only: true` -> the installer preserves it across
+//       updates and /multi-agent:sync refuses to leak it into the public repo)
+//   2. a registry entry in       ~/.claude/multi-agent-preferences.json
+//      at global.routines[]  (name, description, createdAt, source)
+//
+// This tool is the mechanical half; the save/routines/forget SKILLs drive the
+// UX (candidate discovery, pickers, confirmation) and call these subcommands.
+//
+// Zero deps. Never writes under a repo `pipeline/` tree; only ever under
+// <home>/.claude/. Refuses to touch a shipped (non-local-only) command dir.
+//
+// Usage:
+//   node routine-registry.mjs list [--json] [--home <dir>]
+//   node routine-registry.mjs get    --name <n> [--home <dir>]
+//   node routine-registry.mjs add     --name <n> --description <d>
+//        [--description-tr <t>] [--argument-hint <h>] --source <s> --body-file <f> [--home <dir>]
+//   node routine-registry.mjs remove  --name <n> [--home <dir>]
+//
+// Exit: 0 ok, 1 error (validation / collision / not-found), 64 usage.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_NAME = 40;
+const MAX_ROUTINES = 100;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = true;
+      } else {
+        out[key] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function fail(msg) {
+  console.error(`routine-registry: ${msg}`);
+  process.exit(1);
+}
+
+function homeDir(args) {
+  return args.home || process.env.HOME || process.env.USERPROFILE || "";
+}
+function prefsPath(home) {
+  return join(home, ".claude", "multi-agent-preferences.json");
+}
+function routineDir(home, name) {
+  return join(home, ".claude", "commands", "multi-agent", name);
+}
+
+function readPrefs(home) {
+  const p = prefsPath(home);
+  if (!existsSync(p)) return { global: {} };
+  try {
+    const prefs = JSON.parse(readFileSync(p, "utf-8"));
+    if (!prefs.global) prefs.global = {};
+    return prefs;
+  } catch {
+    fail(`could not parse ${p}`);
+  }
+}
+
+function writePrefs(home, prefs) {
+  const p = prefsPath(home);
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(prefs, null, 2)}\n`);
+  renameSync(tmp, p);
+}
+
+function getRoutines(prefs) {
+  return Array.isArray(prefs.global.routines) ? prefs.global.routines : [];
+}
+
+// A dir is a shipped (non-routine) command when it exists and its SKILL.md is
+// NOT marked local-only. Those must never be overwritten or removed.
+function isLocalOnlyDir(dir) {
+  const skill = join(dir, "SKILL.md");
+  if (!existsSync(skill)) return false;
+  return /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+}
+
+function cmdList(home, json) {
+  const routines = getRoutines(readPrefs(home));
+  if (json) {
+    process.stdout.write(`${JSON.stringify(routines, null, 2)}\n`);
+    return;
+  }
+  if (routines.length === 0) {
+    console.log("(no routines saved)");
+    return;
+  }
+  for (const r of routines) {
+    console.log(`${r.name}\t${r.description || ""}\t${r.createdAt || ""}`);
+  }
+}
+
+function cmdGet(home, name) {
+  const r = getRoutines(readPrefs(home)).find((x) => x.name === name);
+  if (!r) fail(`no routine named "${name}"`);
+  process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+}
+
+function buildSkill(args) {
+  const desc = args.description;
+  const descTr = args["description-tr"];
+  const hint = args["argument-hint"] || "[optional args]";
+  const body = readFileSync(args["body-file"], "utf-8").trimEnd();
+  const fm = [
+    "---",
+    `description: ${JSON.stringify(desc)}`,
+    descTr ? `description-tr: ${JSON.stringify(descTr)}` : null,
+    `argument-hint: ${JSON.stringify(hint)}`,
+    "allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion",
+    "local-only: true",
+    "---",
+  ].filter(Boolean);
+  return `${fm.join("\n")}\n\n# multi-agent ${args.name}  -  saved routine\n\n**Input**: $ARGUMENTS\n\n${body}\n`;
+}
+
+function cmdAdd(home, args) {
+  const name = args.name;
+  if (!name || !NAME_RE.test(name) || name.length > MAX_NAME) {
+    fail(`invalid --name (need ${NAME_RE} , <= ${MAX_NAME} chars): ${name}`);
+  }
+  if (!args.description) fail("--description is required");
+  if (!args["body-file"] || !existsSync(args["body-file"])) {
+    fail("--body-file is required and must exist");
+  }
+  const dir = routineDir(home, name);
+  // Collision: an existing non-local-only dir is a shipped command - never touch.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" collides with a shipped command; pick another name`);
+  }
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  if (routines.some((r) => r.name === name)) {
+    fail(`a routine named "${name}" already exists; forget it first or pick another name`);
+  }
+  if (routines.length >= MAX_ROUTINES) fail(`routine cap (${MAX_ROUTINES}) reached`);
+
+  mkdirSync(dir, { recursive: true });
+  const skill = buildSkill(args);
+  // Safety: the generated file MUST be local-only so it never syncs to the repo.
+  if (!/^local-only:\s*true\s*$/m.test(skill)) fail("internal: generated SKILL missing local-only");
+  writeFileSync(join(dir, "SKILL.md"), skill);
+
+  routines.push({
+    name,
+    description: args.description,
+    createdAt: new Date().toISOString(),
+    source: args.source || "user",
+  });
+  prefs.global.routines = routines;
+  writePrefs(home, prefs);
+  console.log(`routine-registry: saved "${name}" -> ${join(dir, "SKILL.md")}`);
+  console.log("routine-registry: available as /multi-agent:" + name + " after a session reload");
+}
+
+function cmdRemove(home, name) {
+  if (!name) fail("--name is required");
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  const idx = routines.findIndex((r) => r.name === name);
+  const dir = routineDir(home, name);
+  // Guard: only remove a dir that is BOTH registered AND local-only.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" is a shipped command, not a routine; refusing to remove`);
+  }
+  if (idx < 0 && !existsSync(dir)) fail(`no routine named "${name}"`);
+  if (existsSync(dir) && isLocalOnlyDir(dir)) rmSync(dir, { recursive: true, force: true });
+  if (idx >= 0) {
+    routines.splice(idx, 1);
+    prefs.global.routines = routines;
+    writePrefs(home, prefs);
+  }
+  console.log(`routine-registry: removed "${name}" (clears from autocomplete on next session reload)`);
+}
+
+function main() {
+  const [, , sub, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  const home = homeDir(args);
+  if (!home) fail("cannot resolve home dir");
+  switch (sub) {
+    case "list":
+      return cmdList(home, Boolean(args.json));
+    case "get":
+      return cmdGet(home, args.name);
+    case "add":
+      return cmdAdd(home, args);
+    case "remove":
+      return cmdRemove(home, args.name);
+    default:
+      console.error("usage: routine-registry.mjs <list|get|add|remove> [flags]  (see header)");
+      process.exit(64);
+  }
+}
+
+main();

package/pipeline/scripts/smoke-fetchers-offline.sh

@@ -354,6 +354,46 @@ assert_in_file "^-i" "$WORK/security-argv.log" "security invoked in -i stdin mod
 assert_not_in_file "$SECRET_VALUE" "$WORK/security-argv.log" "secret absent from security argv"
 assert_in_file "$SECRET_VALUE" "$WORK/security-stdin.log" "secret delivered via stdin"
 
+# -----------------------------------------------------------------------------
+note "7b. fetch-figma-annotations.sh (Tier-2 annotation ingestion)"
+# -----------------------------------------------------------------------------
+expect_rc 1 "no args exits 1 (usage)" \
+  "$SH" "$LIB/fetch-figma-annotations.sh"
+
+# Missing token -> blocked JSON + exit 2 (no network).
+expect_rc 2 "missing token exits 2 with blocked JSON" \
+  env HOME="$FAKE_HOME" USER=smoke \
+  "$SH" "$LIB/fetch-figma-annotations.sh" --file-key ABC --node-id "1:23"
+assert_in_file "missing-token" "$OUT" "blocked JSON names missing-token"
+
+# Fake curl returns a /nodes doc carrying a TR:/EN: annotation; with a stub
+# token the parser must reach + parse it (regression guard for the parser).
+BIN_CURL_ANNOT="$WORK/bin-curl-annot"
+mkdir -p "$BIN_CURL_ANNOT"
+cat > "$BIN_CURL_ANNOT/curl" <<'FAKE'
+#!/bin/bash
+out=""; prev=""
+for a in "$@"; do
+  [ "$prev" = "-o" ] && out="$a"
+  prev="$a"
+done
+if [ -n "$out" ]; then
+  cat > "$out" <<'JSON'
+{"nodes":{"1:23":{"document":{"id":"1:23","name":"Title","type":"TEXT","characters":"Giriniz","annotations":[{"label":"TR: Ucusunuzu secin\nEN: Select your flight"}]}}}}
+JSON
+fi
+printf '200'
+exit 0
+FAKE
+chmod +x "$BIN_CURL_ANNOT/curl"
+
+expect_rc 0 "stub token + annotation doc parses (exit 0)" \
+  env HOME="$FAKE_HOME" USER=smoke FIGMA_PAT=fake-token \
+      PATH="$BIN_CURL_ANNOT:$PATH" \
+  "$SH" "$LIB/fetch-figma-annotations.sh" --file-key ABC --node-id "1:23" --lang-prefixes TR,EN
+assert_in_file "\"mode\": \"prefixed\"" "$OUT" "annotation parsed as prefixed"
+assert_in_file "Select your flight" "$OUT" "EN copy extracted from annotation"
+
 # -----------------------------------------------------------------------------
 note "8. static source checks (bash-3.2 compat + no secrets on argv)"
 # -----------------------------------------------------------------------------
@@ -363,6 +403,7 @@ OWNED_FILES=(
   "$LIB/fetch-swagger.sh"
   "$LIB/fetch-fortify.sh"
   "$LIB/fetch-graylog.sh"
+  "$LIB/fetch-figma-annotations.sh"
   "$LIB/figma-mcp-refresh.sh"
   "$LIB/figma-screenshot.sh"
   "$LIB/credential-store.sh"

package/pipeline/scripts/smoke-generate-issue.sh

@@ -91,11 +91,11 @@ echo ""
 echo "→ 8. registration + count consistency (36)"
 grep -Fq '| `create-jira ' "$DISPATCHER" && pass "dispatcher routing: create-jira" || fail "dispatcher routing missing: generate"
 grep -Fq "create-jira/SKILL.md" "$DISPATCHER" && pass "dispatcher loading row" || fail "dispatcher loading row missing"
-grep -Fq "## 1. Command Inventory (38 commands)" "$CONTRACT" && pass "contract count = 38" || fail "contract count wrong"
+grep -Fq "## 1. Command Inventory (41 commands)" "$CONTRACT" && pass "contract count = 41" || fail "contract count wrong"
 grep -Eq '(^|[ ,])create-jira([ ,]|$)' "$CONTRACT" && pass "contract list has create-jira" || fail "contract list missing generate"
-grep -Fq "**38 commands are synced**" "$SYNC" && pass "sync count = 38" || fail "sync count wrong"
+grep -Fq "**41 commands are synced**" "$SYNC" && pass "sync count = 41" || fail "sync count wrong"
 SYNC_SKILL="$ROOT/pipeline/skills/shared/core/multi-agent-sync/SKILL.md"
-grep -Fq "**38 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 38" || fail "sync SKILL count wrong (Copilot parity)"
+grep -Fq "**41 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 41" || fail "sync SKILL count wrong (Copilot parity)"
 grep -Fq "create-jira" "$ROOT/pipeline/skills/shared/core/multi-agent-help/SKILL.md" && pass "help SKILL lists create-jira" || fail "help SKILL missing create-jira (Copilot parity)"
 grep -c "multi-agent:create-jira" "$HELP" | awk '{exit !($1>=2)}' && pass "help.md has EN + TR entries" || fail "help.md entries incomplete"
 # no stale split-command references anywhere in the synced surfaces