@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/scripts/aggregate-agent-task-metrics.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const teamRootIndex = args.indexOf('--team-root');
+const teamRoot =
+  teamRootIndex >= 0
+    ? path.resolve(args[teamRootIndex + 1] ?? '')
+    : path.join(process.cwd(), '.cursor', 'team');
+const tasksDir = path.join(teamRoot, 'tasks');
+const incomplete = [];
+const attempts = [];
+const tasks = [];
+const gateWaits = [];
+const attributionConfidenceCounts = new Map();
+let unmatchedAttemptCount = 0;
+let duplicateTerminalAttemptCount = 0;
+let duplicateAttemptIdCount = 0;
+let missingLedgerCount = 0;
+let malformedLedgerCount = 0;
+let invalidLedgerCount = 0;
+let unterminatedAttemptCount = 0;
+
+function readMetrics(filePath) {
+  if (!fs.existsSync(filePath)) {
+    incomplete.push({ file: filePath, category: 'missing_ledger', reason: 'missing ledger' });
+    missingLedgerCount += 1;
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    incomplete.push({ file: filePath, category: 'malformed_json', reason: 'malformed JSON' });
+    malformedLedgerCount += 1;
+    return;
+  }
+  if (parsed.schemaVersion !== 1 || !parsed.task || !Array.isArray(parsed.events)) {
+    incomplete.push({ file: filePath, category: 'unsupported_schema', reason: 'unsupported schema' });
+    return;
+  }
+  try {
+    collect(parsed, filePath);
+  } catch (error) {
+    incomplete.push({
+      file: filePath,
+      category: 'invalid_ledger',
+      reason: error instanceof Error ? error.message : 'invalid ledger structure',
+    });
+    invalidLedgerCount += 1;
+  }
+}
+
+function collect(metrics, filePath) {
+  const starts = new Map();
+  const gateStarts = new Map();
+  const terminalAttempts = new Set();
+  let taskCompleted = false;
+  let ledgerIncomplete = false;
+
+  for (const event of metrics.events) {
+    if (event.type === 'attempt_started' && event.attemptId) {
+      if (starts.has(event.attemptId)) {
+        incomplete.push({
+          file: filePath,
+          category: 'duplicate_attempt_id',
+          reason: `duplicate attempt ID ${event.attemptId}`,
+        });
+        duplicateAttemptIdCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      starts.set(event.attemptId, event);
+    }
+    if (event.type === 'attempt_finished' && event.attemptId) {
+      const start = starts.get(event.attemptId);
+      if (!start) {
+        incomplete.push({
+          file: filePath,
+          category: 'unmatched_attempt',
+          reason: `unmatched attempt ${event.attemptId}`,
+        });
+        unmatchedAttemptCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      if (terminalAttempts.has(event.attemptId)) {
+        incomplete.push({
+          file: filePath,
+          category: 'duplicate_terminal_attempt',
+          reason: `duplicate terminal attempt ${event.attemptId}`,
+        });
+        duplicateTerminalAttemptCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      terminalAttempts.add(event.attemptId);
+      const attributionConfidence = event.attributionConfidence ?? 'unknown';
+      attributionConfidenceCounts.set(
+        attributionConfidence,
+        (attributionConfidenceCounts.get(attributionConfidence) ?? 0) + 1,
+      );
+      attempts.push({
+        ...metrics.task,
+        agent: start.agent ?? 'unknown',
+        role: start.role ?? 'unknown',
+        durationMs: Number.isFinite(event.durationMs) ? event.durationMs : null,
+        outcome: event.outcome ?? 'unknown',
+        attributionConfidence,
+      });
+    }
+    if (event.type === 'human_gate_started' && event.eventId) {
+      gateStarts.set(event.eventId, event);
+    }
+    if (event.type === 'human_gate_ended') {
+      const start = event.gateStartedEventId ? gateStarts.get(event.gateStartedEventId) : undefined;
+      const elapsed = start ? Date.parse(event.at) - Date.parse(start.at) : NaN;
+      if (Number.isFinite(elapsed) && elapsed >= 0) gateWaits.push(elapsed);
+    }
+    if (event.type === 'task_completed') taskCompleted = true;
+  }
+
+  for (const attemptId of starts.keys()) {
+    if (terminalAttempts.has(attemptId)) continue;
+    incomplete.push({
+      file: filePath,
+      category: 'unterminated_attempt',
+      reason: `unterminated attempt ${attemptId}`,
+    });
+    unterminatedAttemptCount += 1;
+    ledgerIncomplete = true;
+  }
+
+  if (taskCompleted && !ledgerIncomplete) tasks.push(metrics.task);
+}
+
+function groupBy(items, keyFor) {
+  const groups = new Map();
+  for (const item of items) {
+    const key = keyFor(item);
+    groups.set(key, [...(groups.get(key) ?? []), item]);
+  }
+  return [...groups.values()];
+}
+
+if (!fs.existsSync(tasksDir)) {
+  console.error(`Task directory does not exist: ${tasksDir}`);
+  process.exit(1);
+}
+
+for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+  if (entry.isDirectory()) readMetrics(path.join(tasksDir, entry.name, 'metrics.json'));
+}
+
+const byAgentRole = groupBy(
+  attempts,
+  (item) => `${item.platform}|${item.stack}|${item.preset}|${item.agent}|${item.role}`,
+).map((group) => {
+  const sample = group[0];
+  const durations = group.map((item) => item.durationMs).filter((value) => value !== null);
+  const sumDurationMs = durations.reduce((sum, value) => sum + value, 0);
+  return {
+    platform: sample.platform,
+    stack: sample.stack,
+    preset: sample.preset,
+    agent: sample.agent,
+    role: sample.role,
+    count: group.length,
+    completedCount: group.filter((item) => item.outcome === 'completed').length,
+    sumDurationMs,
+    avgDurationMs: durations.length ? sumDurationMs / durations.length : null,
+  };
+});
+
+const taskCountsByRunId = [...new Map(tasks.map((task) => [task.runId, task])).values()].map((task) => ({
+  runId: task.runId,
+  slug: task.slug,
+  platform: task.platform,
+  stack: task.stack,
+  preset: task.preset,
+  intent: task.intent,
+}));
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      teamRoot,
+      agentRole: byAgentRole,
+      taskCountsByRunId,
+      humanGateWait: {
+        count: gateWaits.length,
+        sumDurationMs: gateWaits.reduce((sum, value) => sum + value, 0),
+      },
+      attributionConfidence: Object.fromEntries(attributionConfidenceCounts),
+      completeness: {
+        missingLedgerCount,
+        malformedLedgerCount,
+        invalidLedgerCount,
+        duplicateAttemptIdCount,
+        unterminatedAttemptCount,
+        unmatchedAttemptCount,
+        duplicateTerminalAttemptCount,
+      },
+      incomplete,
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/check-hook-only-lifecycle.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# FAIL if agent/skill/command prompts still instruct writers to mutate status.json.
+# The orchestration hook is the sole lifecycle writer; agents upsert artifact-manifest receipts.
+# Exit 0 on OK; exit 1 on any FAIL.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+# Imperative write instructions — not "do not mutate" / "runtime owns" / schema docs.
+FORBIDDEN = [
+    re.compile(r"Update `status\.json`:"),
+    re.compile(r"set `status\.json` to"),
+]
+
+hits: list[str] = []
+for path in presets.rglob("*"):
+    if path.suffix not in {".md", ".mdc"}:
+        continue
+    if "/hooks/" in path.as_posix():
+        continue
+    text = path.read_text(encoding="utf-8")
+    rel = path.relative_to(presets)
+    for i, line in enumerate(text.splitlines(), 1):
+        for pat in FORBIDDEN:
+            if pat.search(line):
+                hits.append(f"{rel}:{i}: {line.strip()}")
+
+if hits:
+    print(f"FAIL: {len(hits)} status.json write instruction(s) outside hooks:")
+    for h in hits:
+        print(f"  {h}")
+    sys.exit(1)
+
+print("OK: no agent/skill/command status.json write instructions")
+sys.exit(0)
+PY

package/scripts/check-preset-i18n.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Soft/hard Cyrillic audit for preset prose.
+# Soft (default): warn and exit 0. Hard: AI_RULES_I18N_FAIL=1 → exit 1 on unmarked Cyrillic.
+# Keep marker window: ±3 lines (matches docs/PRESET-ENGLISH-STYLE.md).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+PRESETS="$ROOT/packages/ai-rules/presets"
+SOFT="${AI_RULES_I18N_SOFT:-1}"
+FAIL="${AI_RULES_I18N_FAIL:-0}"
+
+python3 - "$PRESETS" "$SOFT" "$FAIL" <<'PY'
+from __future__ import annotations
+import re, sys
+from pathlib import Path
+
+presets = Path(sys.argv[1])
+soft = sys.argv[2] != "0"
+fail = sys.argv[3] == "1"
+cyr = re.compile(r"[\u0400-\u04FF]")
+keep = re.compile(r"<!--\s*i18n-keep:\s*(E4|E5|E7)(?:\s*[—\-].*?)?\s*-->")
+# Markdown/prose + hook scripts (comments) under presets
+SUFFIXES = {".md", ".mdc", ".sh", ".json", ".mjs", ".ts", ".js"}
+WINDOW = 3  # ±3 lines around a Cyrillic match
+
+violations = []
+kept = 0
+for path in presets.rglob("*"):
+    if path.suffix not in SUFFIXES:
+        continue
+    if "/team/tasks/" in str(path).replace("\\", "/"):
+        continue
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        continue
+    if not cyr.search(text):
+        continue
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if not cyr.search(line):
+            continue
+        lo = max(0, i - WINDOW)
+        hi = min(len(lines), i + WINDOW + 1)
+        if any(keep.search(lines[j]) for j in range(lo, hi)):
+            kept += 1
+            continue
+        violations.append(f"{path}:{i + 1}:{line[:120]}")
+
+print(f"Preset i18n audit: unmarked Cyrillic lines={len(violations)}; kept-marked≈{kept}")
+for v in violations[:50]:
+    print(f"  {v}")
+if len(violations) > 50:
+    print(f"  ... and {len(violations) - 50} more")
+
+if violations and (fail or not soft):
+    if fail:
+        sys.exit(1)
+print("Result:", "WARN (soft)" if violations else "OK")
+sys.exit(0)
+PY