@mmerterden/multi-agent-pipeline 11.4.0 → 11.5.0

package/pipeline/lib/review-watch.sh

@@ -180,6 +180,10 @@ review_one_repo() {
     title=$(jq -r '.title' <<<"$pr")
     url=$(jq -r '.url' <<<"$pr")
 
+    # Advance the cursor candidate for every PR seen (including skips), so a
+    # PR that keeps its reviewed head SHA is not re-fetched on every poll.
+    if [ "$updated_at" \> "$newest_iso" ]; then newest_iso="$updated_at"; fi
+
     # Did we already review THIS head SHA?
     local prev_sha
     prev_sha=$(jq -r --arg n "$pr_num" '.reviewed_prs[$n] // empty' <<<"$state")
@@ -196,12 +200,18 @@ review_one_repo() {
     # (Claude Code session or future webhook handler). review-watch only
     # produces the dispatch list  -  it does not run the LLM itself, because
     # token cost decisions stay with the user.
-    state=$(jq --arg n "$pr_num" --arg s "$head_sha" --arg t "$updated_at" \
-      '.reviewed_prs[$n] = $s | .last_seen_iso = $t' <<<"$state")
-
-    if [ "$updated_at" \> "$newest_iso" ]; then newest_iso="$updated_at"; fi
+    state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
+      '.reviewed_prs[$n] = $s' <<<"$state")
   done < <(jq -c '.[]' <<<"$prs_json")
 
+  # Persist the NEWEST updatedAt seen this scan  -  the previous per-PR
+  # assignment stamped whichever PR the search returned last, which moves
+  # the cursor backwards whenever results are not oldest-first and causes
+  # permanent re-scans. newest_iso only ever grows (seeded from last_seen).
+  if [ -n "$newest_iso" ] && [ "$newest_iso" != "$last_seen" ]; then
+    state=$(jq --arg t "$newest_iso" '.last_seen_iso = $t' <<<"$state")
+  fi
+
   save_state "$repo" "$state"
 }
 
@@ -218,7 +228,13 @@ case "$CMD" in
       while IFS= read -r r; do [ -n "$r" ] && REPOS+=("$r"); done < <(read_repos_from_prefs)
     fi
     [ "${#REPOS[@]}" -eq 0 ] && { err "no repos configured (prefs.reviewWatch.repos)"; exit 2; }
-    for r in "${REPOS[@]}"; do review_one_repo "$r"; done
+    # Per-repo failures (transient gh/network errors) must not kill the run
+    # under set -e; log, continue, and reflect them in the exit code.
+    RC=0
+    for r in "${REPOS[@]}"; do
+      review_one_repo "$r" || { err "scan failed for $r (continuing)"; RC=3; }
+    done
+    exit "$RC"
     ;;
   --watch)
     require_jq
@@ -227,7 +243,11 @@ case "$CMD" in
     [ "$interval" -lt 30 ] && interval=30   # GitHub rate limit guard
     printf 'review-watch: starting loop (interval=%ds)\n' "$interval"
     while :; do
-      while IFS= read -r r; do [ -n "$r" ] && review_one_repo "$r"; done < <(read_repos_from_prefs)
+      # A transient failure on one repo must not kill the watch loop.
+      while IFS= read -r r; do
+        [ -n "$r" ] || continue
+        review_one_repo "$r" || err "scan failed for $r (continuing)"
+      done < <(read_repos_from_prefs)
       sleep "$interval"
     done
     ;;

package/pipeline/lib/shadow-git.sh

@@ -61,6 +61,23 @@ usage() {
 
 shadow_dir() { printf '%s/%s' "$SHADOW_ROOT" "$1"; }
 
+# Task ids become path components under $SHADOW_ROOT, so an unvalidated id
+# like ".." would make prune's `rm -rf` walk out of the shadow tree and
+# delete ~/.claude/state. Allow only [A-Za-z0-9._-]+ and explicitly reject
+# ".", "..", empty, and anything containing a slash.
+require_task_id() {
+  case "${1:-}" in
+    "" | . | ..)
+      err "invalid task id: '${1:-}' (empty, '.' and '..' are rejected)"
+      exit 2
+      ;;
+    *[!A-Za-z0-9._-]*)
+      err "invalid task id: '$1' (allowed characters: A-Z a-z 0-9 . _ -)"
+      exit 2
+      ;;
+  esac
+}
+
 # Wrap git so .git lives in $SHADOW_DIR but worktree is the project root.
 sg() {
   local sd="$1" wt="$2"; shift 2
@@ -74,6 +91,7 @@ iso_now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
 do_init() {
   local task_id="${1:-}" project_root="${2:-}"
   [ -z "$task_id" ] || [ -z "$project_root" ] && { err "usage: init <task-id> <project-root>"; exit 1; }
+  require_task_id "$task_id"
   [ ! -d "$project_root" ] && { err "project root not a directory: $project_root"; exit 1; }
   local sd; sd=$(shadow_dir "$task_id")
   if [ -d "$sd/.git" ]; then
@@ -83,12 +101,16 @@ do_init() {
   mkdir -p "$sd"
   # Bare-ish: .git inside $sd, worktree is the project root.
   git init --quiet "$sd" >/dev/null
-  # Mirror the project's .gitignore so we don't snapshot node_modules / Pods.
+  # Ignore rules must live in $GIT_DIR/info/exclude: the work tree is the
+  # project root, so a .gitignore placed next to the shadow .git is never
+  # read by git. Seed the exclude file with the project's own .gitignore
+  # (protects snapshots even if the project file is deleted mid-run) plus
+  # forced excludes for build artifacts the project may not ignore.
+  mkdir -p "$sd/.git/info"
   if [ -f "$project_root/.gitignore" ]; then
-    cp "$project_root/.gitignore" "$sd/.gitignore"
+    cat "$project_root/.gitignore" >> "$sd/.git/info/exclude"
   fi
-  # Also exclude these from snapshots even if .gitignore omits them.
-  cat >> "$sd/.gitignore" <<EOF
+  cat >> "$sd/.git/info/exclude" <<EOF
 node_modules/
 Pods/
 .build/
@@ -111,6 +133,7 @@ do_snapshot() {
   local task_id="${1:-}" project_root="${2:-}" label="${3:-}"
   [ -z "$task_id" ] || [ -z "$project_root" ] || [ -z "$label" ] && {
     err "usage: snapshot <task-id> <project-root> <label>"; exit 1; }
+  require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id  -  run 'init' first"; exit 1; }
   sg "$sd" "$project_root" add -A >/dev/null 2>&1 || true
@@ -129,6 +152,7 @@ do_snapshot() {
 do_list() {
   local task_id="${1:-}"
   [ -z "$task_id" ] && { err "usage: list <task-id>"; exit 1; }
+  require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id"; exit 1; }
   # Use the embedded `iso:` line from the commit message body so the listing
@@ -141,12 +165,28 @@ do_restore() {
   local task_id="${1:-}" project_root="${2:-}" sha="${3:-}" mode="${4:---files}"
   [ -z "$task_id" ] || [ -z "$project_root" ] || [ -z "$sha" ] && {
     err "usage: restore <task-id> <project-root> <sha> [--files|--state|--both]"; exit 1; }
+  require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id"; exit 1; }
   case "$mode" in
     --files|--both)
       sg "$sd" "$project_root" checkout --quiet "$sha" -- . \
         || { err "git checkout failed"; exit 3; }
+      # `checkout <sha> -- .` restores tracked content but leaves files that
+      # did not exist in the snapshot. Remove both classes of leftovers so a
+      # restore is a full rollback, staying strictly inside the work tree:
+      #   a) files committed in snapshots AFTER $sha (added between sha..HEAD)
+      #   b) files created since the last snapshot (still untracked; `clean`
+      #      respects the info/exclude rules, so ignored trees are untouched)
+      local extra
+      extra=$(sg "$sd" "$project_root" diff --name-only --diff-filter=A "$sha" HEAD 2>/dev/null || true)
+      if [ -n "$extra" ]; then
+        printf '%s\n' "$extra" | while IFS= read -r f; do
+          [ -n "$f" ] && rm -f "$project_root/$f"
+        done
+      fi
+      ( cd "$project_root" && \
+        git --git-dir="$sd/.git" --work-tree="$project_root" clean -fdq ) || true
       printf 'shadow-git: restored files to %s\n' "$sha" >&2
       ;;
     --state)
@@ -161,6 +201,7 @@ do_restore() {
 do_prune() {
   local task_id="${1:-}"; shift || true
   [ -z "$task_id" ] && { err "usage: prune <task-id> [--older-than-days N]"; exit 1; }
+  require_task_id "$task_id"
   local older=""
   while [ "$#" -gt 0 ]; do
     case "$1" in

package/pipeline/lib/vercel-deploy.sh

@@ -110,7 +110,16 @@ cmd_deploy() {
   fi
 
   if [ -z "${VERCEL_TOKEN:-}" ]; then
-    echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('~/.claude/lib/credential-store.sh get <vercel-key>')." >&2
+    # Route the credential-helper hint through the resolver instead of a
+    # hardcoded ~/.claude path so Copilot-only installs get a usable command.
+    # The resolver ships alongside this wrapper in lib/; fall back to the
+    # per-CLI install locations when running from a different cwd layout.
+    # shellcheck source=/dev/null
+    . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
+      || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
+      || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
+      || true
+    echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('${CRED_STORE:-credential-store.sh} get <vercel-key>')." >&2
     echo "Hint: vercel CLI accepts the token via env var; do NOT pass --token= on argv (leaks on retry)." >&2
     exit 1
   fi

package/pipeline/scripts/audit-log-rotate.sh

@@ -34,24 +34,52 @@ mkdir -p "$AUDIT_DIR"
 
 # Rotate today's file (only if it has content)
 if [ -s "$AUDIT_FILE" ]; then
-  STAMP="$(date -u -r "$AUDIT_FILE" +"%Y-%m-%d" 2>/dev/null || date -u +"%Y-%m-%d")"
+  # Portable file-mtime read. BSD `date -r` takes epoch SECONDS (not a file
+  # path), so the previous `date -r "$AUDIT_FILE"` always errored on macOS and
+  # mislabeled every rotated file with today's date.
+  case "$(uname -s)" in
+    Darwin|*BSD*) MTIME="$(stat -f %m "$AUDIT_FILE" 2>/dev/null || true)" ;;
+    *)            MTIME="$(stat -c %Y "$AUDIT_FILE" 2>/dev/null || true)" ;;
+  esac
+  if [ -n "$MTIME" ]; then
+    # BSD: date -r <epoch>; GNU: date -d @<epoch>
+    STAMP="$(date -u -r "$MTIME" +"%Y-%m-%d" 2>/dev/null \
+      || date -u -d "@$MTIME" +"%Y-%m-%d" 2>/dev/null \
+      || date -u +"%Y-%m-%d")"
+  else
+    STAMP="$(date -u +"%Y-%m-%d")"
+  fi
   ROTATED="$AUDIT_DIR/audit.${STAMP}.jsonl"
 
-  # Don't clobber a rotated file from earlier today (multiple invocations)
-  if [ -f "$ROTATED" ]; then
-    cat "$AUDIT_FILE" >> "$ROTATED"
+  # Atomic against concurrent appenders: mv the live inode FIRST, then create
+  # a fresh empty live file. Writers appending via >> to the moved inode land
+  # in the spool and are preserved; the old cat-then-truncate flow lost any
+  # event appended between the copy and the truncate.
+  SPOOL="$AUDIT_DIR/.audit.rotate.$$"
+  mv "$AUDIT_FILE" "$SPOOL"
+  : > "$AUDIT_FILE"
+  chmod 600 "$AUDIT_FILE" 2>/dev/null || true
+
+  # Don't clobber a rotated file from earlier today (multiple invocations).
+  # Earlier rotations may already be gzipped; appending a second gzip member
+  # is valid (gunzip concatenates members).
+  if [ -f "$ROTATED.gz" ] && command -v gzip >/dev/null 2>&1; then
+    if gzip -c "$SPOOL" >> "$ROTATED.gz" 2>/dev/null; then
+      rm -f "$SPOOL"
+    else
+      mv "$SPOOL" "$ROTATED"
+    fi
+  elif [ -f "$ROTATED" ]; then
+    cat "$SPOOL" >> "$ROTATED"
+    rm -f "$SPOOL"
   else
-    mv "$AUDIT_FILE" "$ROTATED"
+    mv "$SPOOL" "$ROTATED"
   fi
 
   # gzip immediately to save space
-  if command -v gzip >/dev/null 2>&1; then
+  if [ -f "$ROTATED" ] && command -v gzip >/dev/null 2>&1; then
     gzip -f "$ROTATED" 2>/dev/null || true
   fi
-
-  # Reset live file (mode 0600  -  sensitive)
-  : > "$AUDIT_FILE"
-  chmod 600 "$AUDIT_FILE" 2>/dev/null || true
 fi
 
 # Drop archives older than KEEP_DAYS

package/pipeline/scripts/check-md-links.mjs

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
-// Internal markdown link checker for the user-facing docs surface.
+// Internal markdown link checker for the user-facing docs surface and the
+// pipeline instruction tree.
 //
-// Scope: root *.md + docs/**/*.md + examples/**/*.md. Verifies that every
-// relative link target ([text](./path) or [text](path#anchor)) resolves to
-// an existing file or directory. External (http/https/mailto) links and
-// pure #anchors are skipped - this is a drift gate for file moves/renames,
-// not a network crawler.
+// Scope: root *.md + docs/**/*.md + examples/**/*.md + pipeline/**/*.md.
+// Verifies that every relative link target ([text](./path) or
+// [text](path#anchor)) resolves to an existing file or directory. Skipped:
+// external (http/https/mailto) links, pure #anchors, template links whose
+// path contains a {placeholder} variable, and links through shell
+// variables ($HOME, ...) - except $HOME/.claude/multi-agent-refs/, which
+// is checked against its repo source (pipeline/multi-agent-refs/) so a
+// ref rename cannot leave stale runtime links behind. This is a drift
+// gate for file moves/renames, not a network crawler.
+//
+// Excluded trees: pipeline/skills/shared/external/ is vendored community
+// skill content - several packs (the Apple HIG set) index upstream
+// references/ companion files that are deliberately not vendored here.
 
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -25,10 +34,13 @@ function mdFiles(dir, acc = []) {
 
 const targets = [
   ...readdirSync(repoRoot).filter((f) => f.endsWith(".md")).map((f) => join(repoRoot, f)),
-  ...["docs", "examples"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
+  ...["docs", "examples", "pipeline"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
   // CHANGELOG-archive.md is frozen history - it legitimately references docs
   // that were deleted in later releases.
-].filter((f) => !f.endsWith("CHANGELOG-archive.md"));
+]
+  .filter((f) => !f.endsWith("CHANGELOG-archive.md"))
+  // Vendored community skill packs (see header note).
+  .filter((f) => !f.includes(join("pipeline", "skills", "shared", "external") + "/"));
 
 const LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
 const errors = [];
@@ -42,9 +54,22 @@ for (const file of targets) {
   for (const match of text.matchAll(LINK_RE)) {
     const raw = match[1];
     if (/^(https?:|mailto:|#)/.test(raw)) continue;
+    // Template placeholders ({fileKey}, {slug}, ...) resolve at runtime,
+    // never on disk - skip them.
+    if (raw.includes("{") || raw.includes("}")) continue;
     const target = raw.split("#")[0];
     if (target === "") continue;
-    const resolved = resolve(dirname(file), decodeURIComponent(target));
+    let resolved;
+    const refsPrefix = "$HOME/.claude/multi-agent-refs/";
+    if (target.startsWith(refsPrefix)) {
+      // Runtime install path with a repo source - check the source tree.
+      resolved = join(repoRoot, "pipeline", "multi-agent-refs", target.slice(refsPrefix.length));
+    } else if (target.includes("$") || target.startsWith("~")) {
+      // Other shell-variable / home paths resolve at runtime only.
+      continue;
+    } else {
+      resolved = resolve(dirname(file), decodeURIComponent(target));
+    }
     if (!existsSync(resolved)) {
       errors.push(`${file.slice(repoRoot.length + 1)}: broken link -> ${raw}`);
     }

package/pipeline/scripts/diff-risk-score.mjs

@@ -85,7 +85,6 @@ function loadDiff() {
     if (!existsSync(DIFF_FILE)) throw new Error(`diff file not found: ${DIFF_FILE}`);
     return readFileSync(DIFF_FILE, "utf8");
   }
-  BASE = resolveBase();
   return git(["diff", "--unified=0", `${BASE}...${HEAD}`]);
 }
 
@@ -295,6 +294,10 @@ function buildRow(stat, addedLines, allChangedPaths) {
 }
 
 function main() {
+  // Resolve the base ref ONCE, before any git diff runs. loadNumstat() and
+  // loadDiff() both interpolate BASE; resolving it lazily inside loadDiff()
+  // used to leave BASE=null for the numstat call (git diff null...HEAD).
+  if (!DIFF_FILE) BASE = resolveBase();
   const numstat = loadNumstat();
   if (numstat.length === 0) {
     process.stderr.write("diff-risk-score: empty diff\n");

package/pipeline/scripts/evidence-gate.mjs

@@ -138,7 +138,16 @@ if (body.trim().length === 0) {
 const successRe = userRegExp(args["success-pattern"], DEFAULT_MARKERS[claim].success, "success");
 const failureRe = userRegExp(args["failure-pattern"], DEFAULT_MARKERS[claim].failure, "failure");
 
-const showsFailure = failureRe.test(body);
+// Zero-count summaries ("0 failed", "0 tests failed out of 10", "0 failures")
+// are success statements, not failure markers. The default \bFAILED\b marker
+// would otherwise flip a passing log to fail - and failure is decisive. Only
+// applied when the DEFAULT failure marker is in play; a caller-supplied
+// --failure-pattern is matched against the raw body untouched.
+const ZERO_FAIL_SUMMARY = /\b0\s+(?:\w+\s+){0,2}(?:failed|failures?|failing)\b/gi;
+const usingDefaultFailure = !args["failure-pattern"] || args["failure-pattern"] === true;
+const failureBody = usingDefaultFailure ? body.replace(ZERO_FAIL_SUMMARY, "") : body;
+
+const showsFailure = failureRe.test(failureBody);
 const showsSuccess = successRe.test(body);
 
 // Failure is DECISIVE. A log that shows a definitive failure marker cannot

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

@@ -1,17 +1,17 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
 .claude/commands	44
-.claude/lib	24
+.claude/lib	25
 .claude/multi-agent-preferences.json	1
 .claude/multi-agent-refs	51
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	180
+.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	180
+.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);
   }