@mmerterden/multi-agent-pipeline 11.3.2 → 11.5.0

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

@@ -1,17 +1,17 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	42
-.claude/lib	24
+.claude/commands	44
+.claude/lib	25
 .claude/multi-agent-preferences.json	1
-.claude/multi-agent-refs	50
+.claude/multi-agent-refs	51
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	178
+.claude/scripts	184
 .claude/settings.json	1
 .claude/skills	428
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
-.copilot/lib	24
+.copilot/lib	25
 .copilot/schemas	23
-.copilot/scripts	178
-.copilot/skills	465
+.copilot/scripts	184
+.copilot/skills	467

package/pipeline/scripts/fixtures/pack-expected-count.txt

@@ -0,0 +1 @@
+943

package/pipeline/scripts/keychain-save.sh

@@ -17,11 +17,11 @@ fi
 echo "Ne tür bir secret kaydedeceksin?"
 echo "  1) Personal Access Token / API Key"
 echo "  2) JSON dosyası (service account vb.)"
-read -p "Seçim (1/2): " CHOICE
+read -rp "Seçim (1/2): " CHOICE
 
 case "$CHOICE" in
     1)
-        read -sp "Token'ı yapıştır (gizli yazılır): " SECRET
+        read -rsp "Token'ı yapıştır (gizli yazılır): " SECRET
         echo ""
         if [ -z "$SECRET" ]; then
             echo "Hata: Token boş olamaz."
@@ -29,7 +29,7 @@ case "$CHOICE" in
         fi
         ;;
     2)
-        read -p "JSON dosya yolunu gir: " JSON_PATH
+        read -rp "JSON dosya yolunu gir: " JSON_PATH
         # Kullanıcının girdiği tırnak işaretlerini temizle
         JSON_PATH="${JSON_PATH//\'/}"
         JSON_PATH="${JSON_PATH//\"/}"
@@ -53,20 +53,24 @@ case "$CHOICE" in
         ;;
 esac
 
-CRED="$HOME/.claude/lib/credential-store.sh"
+# Locate the credential helper via the resolver so Copilot-only installs work.
+# shellcheck disable=SC1090,SC1091
+. "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
+  || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
+  || { echo "Hata: credential-store bulunamadi. Kurulum: npx @mmerterden/multi-agent-pipeline install"; exit 1; }
+CRED="$CRED_STORE"
 
 "$CRED" delete "$SERVICE_NAME" >/dev/null 2>&1 || true
-"$CRED" set "$SERVICE_NAME" "$SECRET"
-
-if [ $? -eq 0 ]; then
+# Secret goes through stdin ("set <key> -") so it never appears on argv.
+if printf '%s' "$SECRET" | "$CRED" set "$SERVICE_NAME" -; then
     echo "Kaydedildi: $SERVICE_NAME (platform: $("$CRED" platform))"
     echo ""
     echo "Okumak icin:"
-    echo "  ~/.claude/lib/credential-store.sh get \"$SERVICE_NAME\""
+    echo "  $CRED get \"$SERVICE_NAME\""
     if [ "$CHOICE" = "2" ]; then
         echo ""
         echo "JSON'a geri cevirmek icin:"
-        echo "  ~/.claude/lib/credential-store.sh get \"$SERVICE_NAME\" | base64 -d"
+        echo "  $CRED get \"$SERVICE_NAME\" | base64 -d"
     fi
 else
     echo "Hata: Kaydedilemedi."

package/pipeline/scripts/lint-skills.mjs

@@ -1,19 +1,27 @@
 #!/usr/bin/env node
 // Frontmatter linter for every SKILL.md shipped by the pipeline.
 //
-// Until v10.0.0 the 217 SKILL.md files were counted by smokes but never
+// Until v10.0.0 the shipped SKILL.md files were counted by smokes but never
 // content-checked, so a skill could ship without the frontmatter that
 // Claude Code / Copilot CLI need to register it. This gate enforces the
 // minimal contract; it is zero-dependency (line-based YAML subset) so it
 // runs inside `npm test` and ci-lite without installs.
 //
-// Contract per SKILL.md:
+// Contract per SKILL.md (errors - fail the gate):
 //   - frontmatter block present (--- ... ---) starting at line 1
 //   - name: required, lowercase kebab-case (underscores tolerated for
 //     legacy skills already published under a snake_case name)
 //   - description: required, non-empty, single line, <= 1024 chars
 //   - user-invocable: when present, must be true or false
 //   - platform: when present, must be ios | android | common | all
+//
+// Spec-conformance signals (warnings - never fail the gate):
+//   - name should match the agent-skills spec pattern
+//     (lowercase letters/digits/hyphens, <= 64 chars)
+//   - description should carry a routing/trigger clause ("use when ...")
+//     so the model can decide when to load the skill
+//   - a body over ~500 lines with no companion-file reference should be
+//     split into references/ files loaded on demand
 
 import { readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
@@ -61,6 +69,16 @@ for (const file of files) {
     fail(file, "missing required field: name");
   } else if (!/^[a-z0-9]+([-_][a-z0-9]+)*$/.test(fields.name)) {
     fail(file, `name is not lowercase kebab/snake-case: "${fields.name}"`);
+  } else {
+    // Spec conformance (warn-only): the agent-skills spec allows lowercase
+    // letters, digits, and hyphens, max 64 chars. Snake_case passes the
+    // legacy error check above but is out of spec.
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(fields.name)) {
+      warn(file, `name is outside the agent-skills spec pattern (hyphens only): "${fields.name}"`);
+    }
+    if (fields.name.length > 64) {
+      warn(file, `name exceeds the spec's 64-char limit (${fields.name.length})`);
+    }
   }
 
   if (!("description" in fields)) {
@@ -81,6 +99,26 @@ for (const file of files) {
     if (!isBlockScalar && words < 6) {
       warn(file, `description is terse (${words} words) - say what it does AND when to use it`);
     }
+    // Routing quality (warn-only): without a trigger clause the model has no
+    // signal for WHEN to load the skill. Heuristic phrase match; block
+    // scalars are skipped for the same parser reason as above.
+    const ROUTING_RE = /\b(use (this|it|when|for|whenever)|when (the|a|an|you|asked|working|building|implementing|writing|reviewing)|triggers?|invoked?( when| for)?|applies when|activated?)\b/i;
+    if (!isBlockScalar && !ROUTING_RE.test(desc)) {
+      warn(file, "description has no routing/trigger clause (e.g. \"use when ...\")");
+    }
+  }
+
+  // Body size (warn-only): the agent-skills guidance is to keep SKILL.md
+  // lean and push detail into companion files loaded on demand. A ~500+
+  // line body that references no companion file loads whole every time.
+  const body = raw.slice(end + 4);
+  const bodyLines = body.split("\n").length;
+  if (bodyLines > 500) {
+    const referencesCompanion =
+      /\]\((?!https?:|mailto:|#)[^)]+\)/.test(body) || /`[^`\n]*\/[^`\n]*\.(md|sh|mjs|json|py|txt)`/.test(body);
+    if (!referencesCompanion) {
+      warn(file, `body is ${bodyLines} lines with no companion-file reference - consider splitting into references/`);
+    }
   }
 
   if ("user-invocable" in fields && !["true", "false"].includes(fields["user-invocable"])) {

package/pipeline/scripts/migrate-prefs.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-// migrate-prefs.mjs  -  migrates multi-agent-preferences.json v2.0.0 → v2.1.0
+// migrate-prefs.mjs  -  migrates multi-agent-preferences.json to the current
+// target schema (see TARGET_VERSION below).
 //
 // Usage:
 //   node migrate-prefs.mjs [--dry-run] [--file <path>]
 //
-// - Idempotent: safe to run multiple times. v2.1.0 files pass through unchanged.
+// - Idempotent: safe to run multiple times. Target-version files pass through unchanged.
 // - Atomic: writes to a .tmp file and rename()s. No partial writes.
 // - Non-destructive: renames gitIdentities → identities, preserves everything else.
 // - Fills defaults for new v2.1.0 fields.
@@ -15,15 +16,33 @@ import os from "node:os";
 
 const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences.json");
 
+// 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 USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
+
 function parseArgs(argv) {
   const args = { file: DEFAULT_FILE, dryRun: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--dry-run") args.dryRun = true;
-    else if (a === "--file") args.file = argv[++i];
-    else if (a === "--help" || a === "-h") {
-      console.log("Usage: migrate-prefs.mjs [--dry-run] [--file <path>]");
+    else if (a === "--file") {
+      const v = argv[++i];
+      if (v === undefined) {
+        console.error("ERROR: --file requires a path argument");
+        console.error(USAGE);
+        process.exit(64);
+      }
+      args.file = v;
+    } else if (a === "--help" || a === "-h") {
+      console.log(USAGE);
       process.exit(0);
+    } else {
+      // A typo like --dry-rnu must never fall through to a real write.
+      console.error(`ERROR: unknown argument: ${a}`);
+      console.error(USAGE);
+      process.exit(64);
     }
   }
   return args;
@@ -142,7 +161,7 @@ function migrate(prefs) {
   // v2.3.0 is the v7.4.0 target  -  adds optional `accounts[]` (per-account host
   // overrides) and `recentAccounts[]` (LRU for autopilot account picker).
   // Both default to empty arrays; old prefs continue to validate without them.
-  const TARGET = "2.3.0";
+  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.2.0") {
@@ -371,7 +390,7 @@ function main() {
   const { out, changes, alreadyMigrated } = migrate(prefs);
 
   if (alreadyMigrated) {
-    console.log(`✓ already v2.1.0  -  no changes: ${args.file}`);
+    console.log(`✓ already v${TARGET_VERSION}  -  no changes: ${args.file}`);
     process.exit(0);
   }
 

package/pipeline/scripts/phase-tracker.sh

@@ -289,6 +289,61 @@ save_state() {
   mv "${TRACKER_FILE}.tmp" "$TRACKER_FILE"
 }
 
+# --- read-modify-write lock ---------------------------------------------------
+# tmp+rename makes each save atomic, but two concurrent invocations (e.g. two
+# parallel Phase 4 reviewers reporting `tokens`) both load the same state and
+# the second save silently drops the first delta. Guard every load->save
+# sequence with a portable mkdir spinlock (macOS bash 3.2: no flock builtin).
+# The wait is bounded and the lock FAILS OPEN with a warning so a stuck lock
+# can never hang the pipeline; a dead owner pid or a lock older than 30s is
+# reclaimed.
+TRACKER_LOCK_DIR=""
+TRACKER_LOCK_HELD=0
+
+state_lock_stale() {
+  local pid mtime now age
+  pid=$(cat "$TRACKER_LOCK_DIR/pid" 2>/dev/null || true)
+  if [ -n "$pid" ]; then
+    kill -0 "$pid" 2>/dev/null && return 1
+    return 0
+  fi
+  mtime=$(stat -f %m "$TRACKER_LOCK_DIR" 2>/dev/null || stat -c %Y "$TRACKER_LOCK_DIR" 2>/dev/null || echo "")
+  [ -z "$mtime" ] && return 1
+  now=$(date +%s)
+  age=$((now - mtime))
+  [ "$age" -gt 30 ]
+}
+
+acquire_state_lock() {
+  TRACKER_LOCK_DIR="${TRACKER_FILE}.lock"
+  mkdir -p "$TRACKER_DIR" 2>/dev/null
+  local tries=0
+  # ~5s bound: 50 tries x 0.1s.
+  while ! mkdir "$TRACKER_LOCK_DIR" 2>/dev/null; do
+    if state_lock_stale; then
+      rm -rf "$TRACKER_LOCK_DIR" 2>/dev/null
+      continue
+    fi
+    tries=$((tries + 1))
+    if [ "$tries" -ge 50 ]; then
+      echo "phase-tracker: WARN  -  state lock busy ($TRACKER_LOCK_DIR); proceeding without lock" >&2
+      return 0
+    fi
+    sleep 0.1
+  done
+  echo "$$" > "$TRACKER_LOCK_DIR/pid" 2>/dev/null
+  TRACKER_LOCK_HELD=1
+}
+
+release_state_lock() {
+  if [ "$TRACKER_LOCK_HELD" = "1" ]; then
+    rm -rf "$TRACKER_LOCK_DIR" 2>/dev/null
+    TRACKER_LOCK_HELD=0
+  fi
+}
+# Never leave a lock behind if a mutating action dies mid-critical-section.
+trap release_state_lock EXIT
+
 render() {
   need_jq
   local state
@@ -509,8 +564,10 @@ case "$ACTION" in
     TRACKER_DIR="$(dirname "$TRACKER_FILE")"
     mkdir -p "$TRACKER_DIR" 2>/dev/null
     NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    acquire_state_lock
     save_state "$(jq -nc --arg id "$TASK_ID" --arg ts "$NOW" \
       '{task_id:$id,started_at:$ts,phases:[]}')"
+    release_state_lock
     # Update pointer so subsequent calls without env can find this tracker.
     # NOTE: the pointer is global; for concurrent runs on the same user account,
     # callers should set MULTI_AGENT_TASK_ID in their shell or prefix every
@@ -528,6 +585,7 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 2 ] || { echo "add needs <phase_id> <name>" >&2; exit 64; }
     PID="$1"; PNAME="$2"
+    acquire_state_lock
     state=$(load_state)
     # Idempotent: a phase id that already exists is a no-op (name, status, and
     # token history are preserved). This is what lets continuation commands
@@ -538,6 +596,7 @@ case "$ACTION" in
       else .phases += [{"id":$id,"name":$name,"status":"pending","subs":[]}]
       end')
     save_state "$new"
+    release_state_lock
     render
     ;;
 
@@ -550,6 +609,7 @@ case "$ACTION" in
       *) echo "bad status: $STATUS" >&2; exit 64 ;;
     esac
     NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    acquire_state_lock
     state=$(load_state)
     # Set status, stamp started_at on first transition to in_progress,
     # stamp completed_at on transition to terminal states (completed/failed/skipped).
@@ -563,6 +623,7 @@ case "$ACTION" in
       )
     ')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.update" "$PID" "$STATUS" "{\"multi_agent.status\": \"$STATUS\"}"
     render
     ;;
@@ -575,6 +636,7 @@ case "$ACTION" in
       pending|in_progress|completed|failed|skipped) ;;
       *) echo "bad status: $SSTATUS" >&2; exit 64 ;;
     esac
+    acquire_state_lock
     state=$(load_state)
     # If sub with this id exists under this phase, update; else append.
     new=$(echo "$state" | jq \
@@ -590,6 +652,7 @@ case "$ACTION" in
         else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.sub" "$PID" "$SNAME" "{\"multi_agent.sub_id\": \"$SID\", \"multi_agent.status\": \"$SSTATUS\"}"
     render
     ;;
@@ -602,6 +665,7 @@ case "$ACTION" in
     case "$T_IN$T_OUT$T_CACHED" in
       *[!0-9]*) echo "tokens: in/out/cached must be non-negative integers" >&2; exit 64 ;;
     esac
+    acquire_state_lock
     state=$(load_state)
     # Additive: add to existing totals so multiple LLM calls accumulate.
     new=$(echo "$state" | jq --arg id "$PID" --argjson ti "$T_IN" --argjson to "$T_OUT" --argjson tc "$T_CACHED" '
@@ -614,6 +678,7 @@ case "$ACTION" in
       )
     ')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.tokens" "$PID" "" "{\"multi_agent.tokens_in_delta\": $T_IN, \"multi_agent.tokens_out_delta\": $T_OUT, \"multi_agent.tokens_cached_delta\": $T_CACHED}"
     # Re-render so live token count is visible on the active phase. Callers
     # that want silent accumulation (e.g. tight loops) can suppress with
@@ -627,6 +692,7 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 3 ] || { echo "meta needs <phase_id> <key> <value>" >&2; exit 64; }
     PID="$1"; KEY="$2"; VALUE="$3"
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg k "$KEY" --arg v "$VALUE" '
       .phases |= map(
@@ -635,6 +701,7 @@ case "$ACTION" in
         else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.meta" "$PID" "$KEY" "{\"multi_agent.meta_key\": \"$KEY\", \"multi_agent.meta_value\": \"$VALUE\"}"
     if [ "${TRACKER_QUIET:-0}" != "1" ]; then
       render
@@ -645,12 +712,14 @@ case "$ACTION" in
     need_jq
     [ "$#" -ge 2 ] || { echo "model needs <phase_id> <model_name>" >&2; exit 64; }
     PID="$1"; MODEL="$2"
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg m "$MODEL" '
       .phases |= map(
         if .id == $id then .model = $m else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.model" "$PID" "" "{\"multi_agent.model\": \"$MODEL\"}"
     if [ "${TRACKER_QUIET:-0}" != "1" ]; then
       render
@@ -667,12 +736,14 @@ case "$ACTION" in
     if [ "${#TEXT}" -gt 60 ]; then
       TEXT="${TEXT:0:59}…"
     fi
+    acquire_state_lock
     state=$(load_state)
     new=$(echo "$state" | jq --arg id "$PID" --arg v "$TEXT" '
       .phases |= map(
         if .id == $id then .meta = ((.meta // {}) + {"Now": $v}) else . end
       )')
     save_state "$new"
+    release_state_lock
     emit_otel_span "phase.now" "$PID" "$TEXT" "{}"
     ;;
 

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

@@ -5,6 +5,45 @@
 
 set -uo pipefail
 
+# Hook-mode fast exit. The Claude Code PreToolUse matcher is the tool name
+# ("Bash"), so this script now fires for EVERY Bash call and receives JSON on
+# stdin: {"tool_name":"Bash","tool_input":{"command":"..."}}. Extract the
+# command and exit 0 immediately unless it actually invokes `git commit`.
+# Direct invocations (empty/non-JSON stdin, e.g. smoke tests or manual runs)
+# fall through to the full scan. Extraction failure also falls through - the
+# only cost is an unnecessary scan, never a skipped one on a real commit.
+if [ ! -t 0 ]; then
+  HOOK_INPUT="$(cat 2>/dev/null || true)"
+  if [ -n "$HOOK_INPUT" ]; then
+    HOOK_COMMAND=""
+    if command -v python3 >/dev/null 2>&1; then
+      HOOK_COMMAND="$(printf '%s' "$HOOK_INPUT" | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))
+except Exception:
+    pass
+' 2>/dev/null || true)"
+    elif command -v node >/dev/null 2>&1; then
+      HOOK_COMMAND="$(printf '%s' "$HOOK_INPUT" | node -e '
+let raw = "";
+process.stdin.on("data", (c) => (raw += c));
+process.stdin.on("end", () => {
+  try {
+    process.stdout.write(String(JSON.parse(raw)?.tool_input?.command ?? ""));
+  } catch { /* fall through to full scan */ }
+});
+' 2>/dev/null || true)"
+    fi
+    if [ -n "$HOOK_COMMAND" ]; then
+      if ! printf '%s\n' "$HOOK_COMMAND" \
+        | grep -qE '(^|[^[:alnum:]_./-])git[[:space:]]+([^|&;]*[[:space:]])?commit([^[:alnum:]_-]|$)'; then
+        exit 0
+      fi
+    fi
+  fi
+fi
+
 if [ -z "$(git diff --cached --name-only 2>/dev/null)" ]; then
   exit 0
 fi