@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/scripts/log-metric.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# log-metric.sh — append a single event to the pipeline metrics log.
+#
+# Append-only JSONL at $METRICS_FILE (default $HOME/.claude/logs/multi-agent/metrics.jsonl).
+# One event per line. Schema:
+#   {
+#     "ts":      "<ISO 8601 timestamp>",
+#     "task_id": "<jira id, github issue, or run id>",
+#     "phase":   "<0..7>",
+#     "event":   "<event name>",
+#     "details": { ...arbitrary key/value pairs... }
+#   }
+#
+# Usage:
+#   log-metric.sh <task_id> <phase> <event> [key=value ...]
+#
+# Examples:
+#   log-metric.sh PROJ-1234 4 review.completed raw_count=8 accepted=3 deferred=2 rejected=3 approved=true duration_ms=42000
+#   log-metric.sh PROJ-1234 4 triage.edge_case case=high-rejection-rate
+#   log-metric.sh PROJ-1234 3 rework.started iteration=2 accepted_blocking=2
+#   log-metric.sh #316 7 task.completed phases=8 review_cycles=2 lang=tr
+#
+# Atomic append: each call uses `>> "$file"` which the kernel guarantees
+# atomic for writes ≤ PIPE_BUF (4 KB on macOS/Linux). One JSONL line is well
+# under that limit, so concurrent pipeline runs don't interleave.
+#
+# Failure mode: if the metrics directory is unwritable, we WARN to stderr but
+# do NOT fail the pipeline. Telemetry is best-effort, never load-bearing.
+
+set -uo pipefail
+
+if [ "$#" -lt 3 ]; then
+  echo "usage: log-metric.sh <task_id> <phase> <event> [key=value ...]" >&2
+  exit 64
+fi
+
+TASK_ID="$1"; shift
+PHASE="$1"; shift
+EVENT="$1"; shift
+
+METRICS_FILE="${METRICS_FILE:-$HOME/.claude/logs/multi-agent/metrics.jsonl}"
+METRICS_DIR="$(dirname "$METRICS_FILE")"
+
+mkdir -p "$METRICS_DIR" 2>/dev/null || {
+  echo "warn: log-metric: cannot create $METRICS_DIR — telemetry skipped" >&2
+  exit 0
+}
+
+# Build details object from key=value args. Keep it shell-portable: no jq required.
+DETAILS="{"
+SEP=""
+for kv in "$@"; do
+  KEY="${kv%%=*}"
+  VAL="${kv#*=}"
+  # Decide if value is bool / int / string. Keep simple — anything not parseable as
+  # int or true/false becomes a JSON string.
+  case "$VAL" in
+    true|false) JSON_VAL="$VAL" ;;
+    ''|*[!0-9]*) JSON_VAL="\"$(printf '%s' "$VAL" | tr -d '\n\r' | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g')\"" ;;
+    *) JSON_VAL="$VAL" ;;
+  esac
+  DETAILS="${DETAILS}${SEP}\"${KEY}\":${JSON_VAL}"
+  SEP=","
+done
+DETAILS="${DETAILS}}"
+
+TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+LINE="{\"ts\":\"${TS}\",\"task_id\":\"${TASK_ID}\",\"phase\":\"${PHASE}\",\"event\":\"${EVENT}\",\"details\":${DETAILS}}"
+
+# Atomic append (one line, well under PIPE_BUF).
+echo "$LINE" >> "$METRICS_FILE" 2>/dev/null || {
+  echo "warn: log-metric: cannot write to $METRICS_FILE — telemetry skipped" >&2
+  exit 0
+}
+
+# v8.3+ opt-in tracker forwarder. When LOG_METRIC_FORWARD_TO_TRACKER=1 and the
+# event details carry tokens_in / tokens_out, mirror them into phase-tracker.sh
+# so the cost block stays in sync with metrics.jsonl from a single call site.
+# Best-effort: never fails the pipeline.
+if [ "${LOG_METRIC_FORWARD_TO_TRACKER:-0}" = "1" ]; then
+  TI=""; TO=""; MODEL=""
+  for kv in "$@"; do
+    case "${kv%%=*}" in
+      tokens_in)  TI="${kv#*=}" ;;
+      tokens_out) TO="${kv#*=}" ;;
+      model)      MODEL="${kv#*=}" ;;
+    esac
+  done
+  if [ -n "$TI" ] && [ -n "$TO" ]; then
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+    if [ -x "$SCRIPT_DIR/phase-tracker.sh" ]; then
+      TRACKER_QUIET=1 "$SCRIPT_DIR/phase-tracker.sh" tokens "$PHASE" "$TI" "$TO" >/dev/null 2>&1 || true
+      if [ -n "$MODEL" ]; then
+        TRACKER_QUIET=1 "$SCRIPT_DIR/phase-tracker.sh" model "$PHASE" "$MODEL" >/dev/null 2>&1 || true
+      fi
+    fi
+  fi
+fi

package/pipeline/scripts/match-skills.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// match-skills.mjs — v7.0.I
+//
+// Given a task description and optionally a list of touched files, score
+// each SKILL.md in the index by relevance. Used by dynamic-skill-loading
+// (prefs.global.dynamicSkillLoading) to inject only matched skills into
+// subagent prompts instead of relying on eager-load.
+//
+// Usage:
+//   match-skills.mjs "<task description>" [--touched-files a.swift,b.kt]
+//                                          [--stack ios|android|backend|…]
+//                                          [--limit N]                       # default 12
+//                                          [--index <path>]                  # default pipeline/skills/.skills-index.json
+//                                          [--json]                          # machine output
+//
+// Output (default human):
+//   <score> <name> [group/platform]  — <description>
+//
+// Output (--json):
+//   { "matches": [ {name, score, reasons, group, relativePath}, ... ] }
+//
+// Scoring (additive, caps at 100):
+//   keyword in description ............  +3 per match (max +15)
+//   keyword in trigger-keywords .......  +6 per match (max +30)
+//   touched-file glob match ...........  +10 per match (max +30)
+//   platform exact match ..............  +10
+//   group is 'core' AND task mentions   +5 (core-always hint)
+//     'multi-agent' / 'pipeline'
+//
+// Exit 0 on success; 1 on setup error.
+
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..", "..");
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0].startsWith("--")) {
+  console.error('Usage: match-skills.mjs "<task text>" [--touched-files a,b] [--stack ios] [--limit 12] [--json]');
+  process.exit(1);
+}
+
+const taskText = args[0];
+const opts = {
+  touchedFiles: [],
+  stack: null,
+  limit: 12,
+  indexPath: join(repoRoot, "pipeline", "skills", ".skills-index.json"),
+  json: false,
+};
+for (let i = 1; i < args.length; i++) {
+  if (args[i] === "--touched-files") opts.touchedFiles = (args[++i] || "").split(",").map((s) => s.trim()).filter(Boolean);
+  else if (args[i] === "--stack") opts.stack = (args[++i] || "").trim().toLowerCase();
+  else if (args[i] === "--limit") opts.limit = parseInt(args[++i], 10) || 12;
+  else if (args[i] === "--index") opts.indexPath = resolve(args[++i]);
+  else if (args[i] === "--json") opts.json = true;
+}
+
+let index;
+try {
+  index = JSON.parse(readFileSync(opts.indexPath, "utf-8"));
+} catch (e) {
+  console.error(`match-skills: cannot read index ${opts.indexPath}: ${e.message}`);
+  console.error("→ run: node pipeline/scripts/build-skills-index.mjs");
+  process.exit(1);
+}
+
+const taskLower = taskText.toLowerCase();
+const taskWords = new Set(
+  taskLower
+    .replace(/[^\w\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length >= 4),
+);
+
+// Very light glob: "*.swift" / "**/Auth/**" style. We avoid adding a full
+// glob lib dependency — zero-dep is a load-bearing project value. Implement
+// a small glob-to-regex translator.
+function globToRe(glob) {
+  let re = "^";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*" && glob[i + 1] === "*") { re += ".*"; i++; }
+    else if (c === "*") re += "[^/]*";
+    else if (c === "?") re += ".";
+    else if (".+()|{}[]^$\\".includes(c)) re += "\\" + c;
+    else re += c;
+  }
+  return new RegExp(re + "$", "i");
+}
+
+const results = [];
+for (const entry of index.entries) {
+  let score = 0;
+  const reasons = [];
+
+  // keyword matches in description (max +15)
+  let descHits = 0;
+  const descLower = (entry.description || "").toLowerCase();
+  for (const w of taskWords) {
+    if (descLower.includes(w)) descHits++;
+  }
+  if (descHits > 0) {
+    const add = Math.min(descHits * 3, 15);
+    score += add;
+    reasons.push({ rule: "desc-keyword", add, detail: `${descHits} term(s)` });
+  }
+
+  // trigger-keywords (max +30, weighted heavier — authors opted in)
+  let kwHits = 0;
+  for (const kw of entry.triggerKeywords || []) {
+    if (taskLower.includes(kw)) kwHits++;
+  }
+  if (kwHits > 0) {
+    const add = Math.min(kwHits * 6, 30);
+    score += add;
+    reasons.push({ rule: "trigger-keyword", add, detail: `${kwHits} hit(s)` });
+  }
+
+  // trigger-paths vs touched files (max +30)
+  let pathHits = 0;
+  if (opts.touchedFiles.length > 0 && entry.triggerPaths?.length > 0) {
+    for (const glob of entry.triggerPaths) {
+      const re = globToRe(glob);
+      if (opts.touchedFiles.some((f) => re.test(f))) pathHits++;
+    }
+  }
+  if (pathHits > 0) {
+    const add = Math.min(pathHits * 10, 30);
+    score += add;
+    reasons.push({ rule: "trigger-path", add, detail: `${pathHits} glob match(es)` });
+  }
+
+  // platform match (+10)
+  if (opts.stack && entry.platform && entry.platform === opts.stack) {
+    score += 10;
+    reasons.push({ rule: "platform", add: 10, detail: `platform=${entry.platform}` });
+  }
+
+  // core-always hint (+5) — only when task text mentions the orchestrator
+  if (entry.group === "core" && /\b(multi[- ]agent|pipeline|orchestrator)\b/i.test(taskText)) {
+    score += 5;
+    reasons.push({ rule: "core-hint", add: 5, detail: "core orchestration mentioned" });
+  }
+
+  if (score > 0) {
+    results.push({ ...entry, score: Math.min(score, 100), reasons });
+  }
+}
+
+results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+const top = results.slice(0, opts.limit);
+
+if (opts.json) {
+  process.stdout.write(JSON.stringify({ task: taskText, matches: top }, null, 2) + "\n");
+} else {
+  for (const m of top) {
+    const tag = `[${m.group}${m.platform ? "/" + m.platform : ""}]`;
+    const desc = (m.description || "").slice(0, 80);
+    console.log(`${String(m.score).padStart(3)} ${m.name.padEnd(32)} ${tag.padEnd(18)} ${desc}`);
+  }
+  if (top.length === 0) console.log("(no skills matched)");
+}
+
+process.exit(0);

package/pipeline/scripts/memory-load.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# memory-load.sh — v6.2.E
+#
+# Reads the per-repo memory at $PROJECT_ROOT/.multi-agent/memory/ and prints
+# a compact markdown block suitable for Phase 0 context injection. Falls back
+# to an empty line and exit 0 if memory is absent or disabled.
+#
+# Usage: memory-load.sh <project-root>
+#
+# Honors `prefs.global.perRepoMemory`. When the pref is off OR the prefs file
+# cannot be located, exits silently (non-zero ignored by caller).
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:?usage: memory-load.sh <project-root>}"
+MEM_DIR="$PROJECT_ROOT/.multi-agent/memory"
+MEM_INDEX="$MEM_DIR/MEMORY.md"
+
+# Pref-gate: locate prefs.json (home-dir first, then project-specific).
+prefs_file=""
+for candidate in \
+  "$HOME/.claude/preferences.json" \
+  "$HOME/.config/multi-agent-pipeline/preferences.json"
+do
+  [ -f "$candidate" ] && { prefs_file="$candidate"; break; }
+done
+
+if [ -n "$prefs_file" ] && command -v jq >/dev/null 2>&1; then
+  enabled=$(jq -r '.global.perRepoMemory // false' "$prefs_file" 2>/dev/null || echo "false")
+  [ "$enabled" = "true" ] || exit 0
+else
+  # No prefs file or no jq — treat as opt-out to avoid surprising new users.
+  exit 0
+fi
+
+[ -f "$MEM_INDEX" ] || exit 0
+
+# Emit Phase 0 injection block — capped at 30 lines to stay within token budget.
+# If MEMORY.md is larger, the first 30 pointer lines are printed; individual
+# memory files are NOT inlined (caller reads them on-demand when a pointer
+# looks relevant).
+printf '<repo-memory path="%s">\n' "$MEM_DIR"
+head -30 "$MEM_INDEX"
+printf '</repo-memory>\n'
+
+exit 0

package/pipeline/scripts/memory-save.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# memory-save.sh — v6.2.E
+#
+# Writes a single per-repo memory file and updates the MEMORY.md index.
+# Called by Phase 7's synthesis step (or any user skill that wants to
+# persist a finding). Opt-in via prefs.global.perRepoMemory.
+#
+# Usage:
+#   memory-save.sh <project-root> <type> <slug> <body-file>
+#
+#   type     = user | feedback | project | reference
+#   slug     = kebab-case filename fragment (e.g. "audit-exhaustiveness")
+#   body-file= path to a file containing the frontmatter-wrapped memory body
+#              (or "-" to read body from stdin)
+#
+# Writes to $PROJECT_ROOT/.multi-agent/memory/<type>_<slug>.md and prepends
+# a bullet to MEMORY.md. Idempotent — overwriting an existing slug replaces
+# the file but leaves the index entry position unchanged.
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:?usage: memory-save.sh <project-root> <type> <slug> <body-file|->}"
+TYPE="${2:?missing type}"
+SLUG="${3:?missing slug}"
+BODY_SRC="${4:?missing body file (or '-')}"
+
+case "$TYPE" in
+  user|feedback|project|reference) ;;
+  *) echo "memory-save: invalid type '$TYPE' (expected user|feedback|project|reference)" >&2; exit 1 ;;
+esac
+
+[[ "$SLUG" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "memory-save: invalid slug '$SLUG' (kebab-case [a-z0-9-])" >&2; exit 1; }
+
+MEM_DIR="$PROJECT_ROOT/.multi-agent/memory"
+MEM_INDEX="$MEM_DIR/MEMORY.md"
+FILE="$MEM_DIR/${TYPE}_${SLUG}.md"
+
+mkdir -p "$MEM_DIR"
+
+# Gitignore guard — never commit memory to the repo.
+GITIGNORE="$PROJECT_ROOT/.multi-agent/.gitignore"
+if [ ! -f "$GITIGNORE" ]; then
+  cat > "$GITIGNORE" <<'GI'
+# Per-repo memory is local-only — never commit.
+memory/
+GI
+fi
+
+if [ "$BODY_SRC" = "-" ]; then
+  body="$(cat)"
+else
+  [ -f "$BODY_SRC" ] || { echo "memory-save: body file '$BODY_SRC' not found" >&2; exit 1; }
+  body="$(cat "$BODY_SRC")"
+fi
+
+printf '%s\n' "$body" > "$FILE"
+
+# Derive index entry: use the first-line description (or slug as fallback).
+description=$(awk '/^description:/ {sub(/^description: */, ""); gsub(/^"|"$/, ""); print; exit}' "$FILE" || true)
+[ -n "$description" ] || description="$SLUG"
+
+# Strip existing index line for this file (idempotent), then append new line.
+if [ -f "$MEM_INDEX" ]; then
+  grep -v "](${TYPE}_${SLUG}\.md)" "$MEM_INDEX" > "${MEM_INDEX}.tmp" || true
+  mv "${MEM_INDEX}.tmp" "$MEM_INDEX"
+else
+  printf '# Per-repo memory index\n\n' > "$MEM_INDEX"
+fi
+
+title=$(awk '/^name:/ {sub(/^name: */, ""); gsub(/^"|"$/, ""); print; exit}' "$FILE" || true)
+[ -n "$title" ] || title="$SLUG"
+
+printf -- '- [%s](%s_%s.md) — %s\n' "$title" "$TYPE" "$SLUG" "$description" >> "$MEM_INDEX"
+
+printf 'memory-save: wrote %s\n' "$FILE"
+exit 0