Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(gateguard): add metrics event schema and report script

Jeffrey Montoyad591999ec070
diff --git a/package.json b/package.json
index 57357af0e..59c1feda0 100644
--- a/package.json
+++ b/package.json
@@ -124,6 +124,7 @@
"scripts/memory.js",
"scripts/memory-mcp.mjs",
"scripts/gemini-adapt-agents.js",
+ "scripts/gateguard-report.js",
"scripts/harness-adapter-compliance.js",
"scripts/harness-audit.js",
"scripts/eval-harness.js",
diff --git a/scripts/gateguard-report.js b/scripts/gateguard-report.js
new file mode 100644
index 000000000..10c3bafcb
--- /dev/null
+++ b/scripts/gateguard-report.js
@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { METRICS_FILE_NAME, isMetricsEvent } = require('./lib/gateguard-metrics');
+
+const DENIAL_DECISIONS = new Set(['deny', 'routine-deny', 'destructive-deny']);
+const FIRST_TOUCH_DECISIONS = ['deny', 'credit', 'sibling', 'cap', 'trivial'];
+const NEAR_MISS_PREFIX = 'near-miss:';
+const TOP_QUESTIONS = 10;
+
+function showHelp() {
+ console.log(`
+Usage: node scripts/gateguard-report.js [options]
+
+Summarises GateGuard decision metrics (written when GATEGUARD_METRICS=1).
+
+Options:
+ --dir <path> Directory holding metrics.jsonl (default: GATEGUARD_STATE_DIR or ~/.gateguard)
+ --json Emit machine-readable JSON
+ --help Show this help text
+`);
+}
+
+function parseArgs(argv) {
+ const options = { dir: null, json: false, help: false };
+ for (let index = 0; index < argv.length; index++) {
+ const arg = argv[index];
+ if (arg === '--json') {
+ options.json = true;
+ } else if (arg === '--help' || arg === '-h') {
+ options.help = true;
+ } else if (arg === '--dir') {
+ const value = argv[index + 1];
+ if (!value || value.startsWith('--')) throw new Error('Missing value for --dir');
+ options.dir = value;
+ index++;
+ } else if (arg.startsWith('--dir=')) {
+ const value = arg.slice('--dir='.length);
+ if (!value) throw new Error('Missing value for --dir');
+ options.dir = value;
+ } else {
+ throw new Error(`Unknown argument: ${arg}`);
+ }
+ }
+ return options;
+}
+
+function defaultDir() {
+ return process.env.GATEGUARD_STATE_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.gateguard');
+}
+
+/** Valid events from `metrics.jsonl.1` then `metrics.jsonl` in `dir`, with the count of skipped lines. */
+function loadMetrics(dir) {
+ const current = path.join(dir, METRICS_FILE_NAME);
+ const files = [`${current}.1`, current].filter(file => {
+ try {
+ return fs.statSync(file).isFile();
+ } catch (_) {
+ return false;
+ }
+ });
+ const events = [];
+ let skipped = 0;
+ for (const file of files) {
+ for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+ if (!line.trim()) continue;
+ let parsed = null;
+ try {
+ parsed = JSON.parse(line);
+ } catch (_) {
+ parsed = null;
+ }
+ if (isMetricsEvent(parsed)) {
+ events.push(parsed);
+ } else {
+ skipped++;
+ }
+ }
+ }
+ return { dir, files, events, skipped };
+}
+
+function increment(counts, key) {
+ counts[key] = (counts[key] || 0) + 1;
+}
+
+function byCount(counts) {
+ return Object.fromEntries(Object.entries(counts).sort(([a, x], [b, y]) => y - x || (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+function ratio(count, total) {
+ return total > 0 ? count / total : null;
+}
+
+function summarizeGroup(events) {
+ const decisions = {};
+ const denialClasses = {};
+ const denialReasons = {};
+ const questions = {};
+ const firstTouchCounts = Object.fromEntries(FIRST_TOUCH_DECISIONS.map(decision => [decision, 0]));
+ let denials = 0;
+ let nearMiss = 0;
+ for (const event of events) {
+ increment(decisions, event.decision);
+ if (Object.hasOwn(firstTouchCounts, event.decision)) firstTouchCounts[event.decision]++;
+ if (DENIAL_DECISIONS.has(event.decision)) {
+ denials++;
+ increment(denialClasses, event.class || 'shell');
+ increment(denialReasons, event.reason || 'unknown');
+ }
+ if (event.decision === 'deny') {
+ if (typeof event.reason === 'string' && event.reason.startsWith(NEAR_MISS_PREFIX)) nearMiss++;
+ for (const id of event.questions || []) increment(questions, id);
+ }
+ }
+ const firstTouchTotal = FIRST_TOUCH_DECISIONS.reduce((sum, decision) => sum + firstTouchCounts[decision], 0);
+ return {
+ events: events.length,
+ first: events.length > 0 ? events[0].ts : null,
+ last: events.length > 0 ? events[events.length - 1].ts : null,
+ decisions: byCount(decisions),
+ denials: { total: denials, byClass: byCount(denialClasses), byReason: byCount(denialReasons) },
+ nearMiss: { count: nearMiss, of: firstTouchCounts.deny, share: ratio(nearMiss, firstTouchCounts.deny) },
+ firstTouch: {
+ total: firstTouchTotal,
+ counts: firstTouchCounts,
+ rates: Object.fromEntries(FIRST_TOUCH_DECISIONS.map(decision => [decision, ratio(firstTouchCounts[decision], firstTouchTotal)]))
+ },
+ routineReadonlyPasses: decisions['routine-readonly'] || 0,
+ topQuestions: Object.entries(byCount(questions)).slice(0, TOP_QUESTIONS)
+ };
+}
+
+/** Totals and per-session summaries of metrics events. */
+function summarize(events) {
+ const bySession = new Map();
+ for (const event of events) {
+ if (!bySession.has(event.session)) bySession.set(event.session, []);
+ bySession.get(event.session).push(event);
+ }
+ const sessions = {};
+ for (const [session, sessionEvents] of bySession) sessions[session] = summarizeGroup(sessionEvents);
+ return { total: summarizeGroup(events), sessions };
+}
+
+function percent(value) {
+ return value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`;
+}
+
+function counts(entries) {
+ const list = Array.isArray(entries) ? entries : Object.entries(entries);
+ return list.length > 0 ? list.map(([key, count]) => `${key} ${count}`).join(', ') : 'none';
+}
+
+function formatGroup(title, group) {
+ const rates = FIRST_TOUCH_DECISIONS.map(decision => `${decision} ${percent(group.firstTouch.rates[decision])}`).join(', ');
+ return [
+ title,
+ ` decisions: ${counts(group.decisions)}`,
+ ` denials: ${group.denials.total}`,
+ ` denials by class: ${counts(group.denials.byClass)}`,
+ ` denials by reason: ${counts(group.denials.byReason)}`,
+ ` near-miss share of first-touch denials: ${percent(group.nearMiss.share)} (${group.nearMiss.count} of ${group.nearMiss.of})`,
+ ` first-touch outcomes (${group.firstTouch.total}): ${rates}`,
+ ` routine read-only passes: ${group.routineReadonlyPasses}`,
+ ` most-asked questions: ${counts(group.topQuestions)}`
+ ].join('\n');
+}
+
+/** Plain-text report for `loadMetrics` output plus its `summarize` report. */
+function formatReport({ dir, events, skipped, report }) {
+ const sessionIds = Object.keys(report.sessions);
+ const header =
+ `GateGuard metrics${dir ? ` in ${dir}` : ''}: ${events.length} events in ${sessionIds.length} sessions` +
+ (skipped > 0 ? ` (${skipped} malformed lines skipped)` : '');
+ const sections = [header, '', formatGroup('Total', report.total)];
+ for (const session of sessionIds) {
+ const group = report.sessions[session];
+ sections.push('', formatGroup(`Session ${session} (${group.first} to ${group.last})`, group));
+ }
+ return `${sections.join('\n')}\n`;
+}
+
+function main() {
+ try {
+ const options = parseArgs(process.argv.slice(2));
+ if (options.help) {
+ showHelp();
+ return;
+ }
+ const loaded = loadMetrics(options.dir || defaultDir());
+ const report = summarize(loaded.events);
+ if (options.json) {
+ const output = { dir: loaded.dir, files: loaded.files, events: loaded.events.length, skipped: loaded.skipped, ...report };
+ process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+ } else if (loaded.events.length === 0) {
+ process.stdout.write(
+ `No GateGuard metrics in ${loaded.dir}` +
+ (loaded.skipped > 0 ? ` (${loaded.skipped} malformed lines skipped)` : '') +
+ '. Set GATEGUARD_METRICS=1 to record gate decisions.\n'
+ );
+ } else {
+ process.stdout.write(formatReport({ ...loaded, report }));
+ }
+ } catch (error) {
+ process.stderr.write(`Error: ${error.message}\n`);
+ process.exit(1);
+ }
+}
+
+if (require.main === module) {
+ main();
+}
+
+module.exports = { formatReport, loadMetrics, parseArgs, summarize };
diff --git a/scripts/lib/gateguard-metrics.js b/scripts/lib/gateguard-metrics.js
new file mode 100644
index 000000000..c8ac0651f
--- /dev/null
+++ b/scripts/lib/gateguard-metrics.js
@@ -0,0 +1,120 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const METRICS_SCHEMA_VERSION = 1;
+const METRICS_FILE_NAME = 'metrics.jsonl';
+const METRICS_MAX_BYTES = 1024 * 1024;
+const SESSION_DIGEST_LENGTH = 12;
+const CODE_MAX_LENGTH = 48;
+const CODE_PATTERN = /^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?$/;
+const SESSION_PATTERN = /^[0-9a-f]{12}$/;
+
+const DECISIONS = Object.freeze([
+ 'deny',
+ 'credit',
+ 'sibling',
+ 'cap',
+ 'trivial',
+ 'pass-checked',
+ 'pass-exempt',
+ 'pass-subagent',
+ 'routine-deny',
+ 'routine-readonly',
+ 'destructive-deny',
+ 'pass'
+]);
+const DECISION_SET = new Set(DECISIONS);
+const TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'Bash', 'PowerShell']);
+
+function isCode(value) {
+ return typeof value === 'string' && value.length <= CODE_MAX_LENGTH && CODE_PATTERN.test(value);
+}
+
+function codeOrNull(value) {
+ return isCode(value) ? value : null;
+}
+
+function sessionDigest(sessionKey) {
+ return crypto.createHash('sha256').update(String(sessionKey || '')).digest('hex').slice(0, SESSION_DIGEST_LENGTH);
+}
+
+function profileFields(profile) {
+ if (!profile || typeof profile !== 'object') return null;
+ return {
+ known: profile.known === true,
+ language: codeOrNull(profile.language),
+ touchesPublicSurface: profile.touchesPublicSurface === true,
+ touchesData: profile.touchesData === true,
+ trivial: profile.trivial === true
+ };
+}
+
+/** One metrics line for a gate decision, or null when the decision or tool is not recorded. */
+function metricsEvent({ sessionKey, tool, cls, decision, reason, questions, sensitive, profile, now = Date.now() }) {
+ if (!DECISION_SET.has(decision) || !TOOLS.has(tool)) return null;
+ return {
+ v: METRICS_SCHEMA_VERSION,
+ ts: new Date(now).toISOString(),
+ session: sessionDigest(sessionKey),
+ tool,
+ class: codeOrNull(cls),
+ decision,
+ reason: codeOrNull(reason),
+ questions: Array.isArray(questions) ? questions.filter(isCode) : null,
+ sensitive: sensitive === true,
+ profile: profileFields(profile)
+ };
+}
+
+/** Whether a parsed line has the shape `metricsEvent` writes. */
+function isMetricsEvent(value) {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+ if (value.v !== METRICS_SCHEMA_VERSION || typeof value.ts !== 'string') return false;
+ if (typeof value.session !== 'string' || !SESSION_PATTERN.test(value.session)) return false;
+ if (!TOOLS.has(value.tool) || !DECISION_SET.has(value.decision)) return false;
+ if (value.class !== null && !isCode(value.class)) return false;
+ if (value.reason !== null && !isCode(value.reason)) return false;
+ if (value.questions !== null && !(Array.isArray(value.questions) && value.questions.every(isCode))) return false;
+ return typeof value.sensitive === 'boolean';
+}
+
+/** Append events to `<dir>/metrics.jsonl` in one write, rotating to `.1` past the size cap; never throws. */
+function appendMetrics(dir, events) {
+ try {
+ const lines = events
+ .filter(Boolean)
+ .map(event => `${JSON.stringify(event)}\n`)
+ .join('');
+ if (!lines) return false;
+ const file = path.join(dir, METRICS_FILE_NAME);
+ fs.mkdirSync(dir, { recursive: true });
+ let size = 0;
+ try {
+ const stat = fs.statSync(file);
+ size = stat.isFile() ? stat.size : 0;
+ } catch (_) {
+ size = 0;
+ }
+ if (size > 0 && size + Buffer.byteLength(lines) > METRICS_MAX_BYTES) {
+ fs.renameSync(file, `${file}.1`);
+ }
+ fs.appendFileSync(file, lines, { encoding: 'utf8', mode: 0o600 });
+ return true;
+ } catch (_) {
+ return false;
+ }
+}
+
+module.exports = {
+ DECISIONS,
+ METRICS_FILE_NAME,
+ METRICS_MAX_BYTES,
+ METRICS_SCHEMA_VERSION,
+ appendMetrics,
+ isMetricsEvent,
+ metricsEvent,
+ sessionDigest
+};
diff --git a/tests/fixtures/gateguard-metrics/metrics.jsonl b/tests/fixtures/gateguard-metrics/metrics.jsonl
new file mode 100644
index 000000000..06e6fd4ff
--- /dev/null
+++ b/tests/fixtures/gateguard-metrics/metrics.jsonl
@@ -0,0 +1,17 @@
+{"v":1,"ts":"2026-09-01T10:02:00.000Z","session":"aaaaaaaaaaaa","tool":"Edit","class":"code","decision":"deny","reason":"near-miss:out-of-scope","questions":["local-callers","quote-instruction"],"sensitive":false,"profile":{"known":true,"language":"js","touchesPublicSurface":false,"touchesData":false,"trivial":false}}
+not json
+{"v":1,"ts":"2026-09-01T10:03:00.000Z","session":"aaaaaaaaaaaa","tool":"Edit","class":"code","decision":"credit","reason":"prior-search","questions":null,"sensitive":false,"profile":null}
+{"v":2,"ts":"2026-09-01T10:03:30.000Z","session":"aaaaaaaaaaaa","tool":"Edit","class":"code","decision":"deny","reason":"first-touch","questions":[],"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T10:04:00.000Z","session":"aaaaaaaaaaaa","tool":"Edit","class":"code","decision":"trivial","reason":"comment-whitespace","questions":null,"sensitive":false,"profile":{"known":true,"language":"js","touchesPublicSurface":false,"touchesData":false,"trivial":true}}
+{"v":1,"ts":"2026-09-01T10:05:00.000Z","session":"aaaaaaaaaaaa","tool":"Bash","class":null,"decision":"routine-deny","reason":"first-command","questions":null,"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T11:00:00.000Z","session":"NOT-A-HASH","tool":"Edit","class":"code","decision":"deny","reason":"first-touch","questions":[],"sensitive":false,"profile":null}
+
+{"v":1,"ts":"2026-09-01T11:00:30.000Z","session":"bbbbbbbbbbbb","tool":"Edit","class":"code","decision":"allow","reason":"first-touch","questions":null,"sensitive":false,"profile":null}
+[]
+{"v":1,"ts":"2026-09-01T11:00:40.000Z","session":"bbbbbbbbbbbb","tool":"Edit","class":"code","decision":"deny","reason":"/home/user/secret.js","questions":null,"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T11:01:00.000Z","session":"bbbbbbbbbbbb","tool":"Write","class":"code","decision":"deny","reason":"first-touch","questions":["callers","no-duplicate","quote-instruction"],"sensitive":false,"profile":{"known":true,"language":"py","touchesPublicSurface":true,"touchesData":false,"trivial":false}}
+{"v":1,"ts":"2026-09-01T11:02:00.000Z","session":"bbbbbbbbbbbb","tool":"Write","class":"code","decision":"sibling","reason":"same-turn-dir","questions":null,"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T11:03:00.000Z","session":"bbbbbbbbbbbb","tool":"Edit","class":"config","decision":"deny","reason":"sensitive","questions":["config-reader","config-effect","no-plaintext-secrets","quote-instruction"],"sensitive":true,"profile":null}
+{"v":1,"ts":"2026-09-01T11:04:00.000Z","session":"bbbbbbbbbbbb","tool":"Edit","class":"code","decision":"cap","reason":"max-denials","questions":null,"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T11:05:00.000Z","session":"bbbbbbbbbbbb","tool":"PowerShell","class":null,"decision":"destructive-deny","reason":"destructive","questions":null,"sensitive":false,"profile":null}
+{"v":1,"ts":"2026-09-01T11:06:00.000Z","session":"bbbbbbbbbbbb","tool":"Edit","class":"code","decision":"pass-checked","reason":"checked","questions":null,"sensitive":false,"profile":null}
diff --git a/tests/fixtures/gateguard-metrics/metrics.jsonl.1 b/tests/fixtures/gateguard-metrics/metrics.jsonl.1
new file mode 100644
index 000000000..34ea592b4
--- /dev/null
+++ b/tests/fixtures/gateguard-metrics/metrics.jsonl.1
@@ -0,0 +1,2 @@
+{"v":1,"ts":"2026-09-01T10:00:00.000Z","session":"aaaaaaaaaaaa","tool":"Edit","class":"code","decision":"deny","reason":"first-touch","questions":["importers","public-api","quote-instruction"],"sensitive":false,"profile":{"known":true,"language":"js","touchesPublicSurface":true,"touchesData":false,"trivial":false}}
+{"v":1,"ts":"2026-09-01T10:01:00.000Z","session":"aaaaaaaaaaaa","tool":"Bash","class":null,"decision":"routine-readonly","reason":"readonly","questions":null,"sensitive":false,"profile":null}
diff --git a/tests/lib/gateguard-metrics.test.js b/tests/lib/gateguard-metrics.test.js
new file mode 100644
index 000000000..12b204067
--- /dev/null
+++ b/tests/lib/gateguard-metrics.test.js
@@ -0,0 +1,153 @@
+/**
+ * Tests for scripts/lib/gateguard-metrics.js
+ */
+
+'use strict';
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+ DECISIONS,
+ METRICS_FILE_NAME,
+ METRICS_MAX_BYTES,
+ metricsEvent,
+ appendMetrics,
+ isMetricsEvent
+} = require('../../scripts/lib/gateguard-metrics');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` \u2713 ${name}`);
+ passed++;
+ } catch (error) {
+ console.log(` \u2717 ${name}`);
+ console.log(` Error: ${error.message}`);
+ failed++;
+ }
+}
+
+const NOW = Date.parse('2026-09-01T10:00:00.000Z');
+const base = { sessionKey: 'sess-1', tool: 'Edit', decision: 'deny', reason: 'first-touch', now: NOW };
+
+console.log('\n=== Testing gateguard-metrics ===\n');
+
+test('builds a schema 1 event with a 12-character session digest', () => {
+ const event = metricsEvent({
+ ...base,
+ cls: 'code',
+ questions: ['importers', 'quote-instruction'],
+ sensitive: false,
+ profile: { known: true, language: 'js', touchesPublicSurface: true, touchesData: false, trivial: false, extra: 'x' }
+ });
+ assert.deepStrictEqual(event, {
+ v: 1,
+ ts: '2026-09-01T10:00:00.000Z',
+ session: crypto.createHash('sha256').update('sess-1').digest('hex').slice(0, 12),
+ tool: 'Edit',
+ class: 'code',
+ decision: 'deny',
+ reason: 'first-touch',
+ questions: ['importers', 'quote-instruction'],
+ sensitive: false,
+ profile: { known: true, language: 'js', touchesPublicSurface: true, touchesData: false, trivial: false }
+ });
+ assert.ok(isMetricsEvent(event));
+});
+
+test('returns null for unknown decisions or tools', () => {
+ assert.strictEqual(metricsEvent({ ...base, decision: 'allow' }), null);
+ assert.strictEqual(metricsEvent({ ...base, tool: 'Read' }), null);
+});
+
+test('drops any class, reason, question or language that is not a short code', () => {
+ const event = metricsEvent({
+ ...base,
+ cls: '/src/app.js',
+ reason: 'rm -rf /',
+ questions: ['importers', '/etc/passwd', 'x'.repeat(100)],
+ profile: { known: true, language: 'C:\\x' }
+ });
+ assert.strictEqual(event.class, null);
+ assert.strictEqual(event.reason, null);
+ assert.deepStrictEqual(event.questions, ['importers']);
+ assert.strictEqual(event.profile.language, null);
+});
+
+test('keeps near-miss reason codes', () => {
+ assert.strictEqual(metricsEvent({ ...base, reason: 'near-miss:out-of-scope' }).reason, 'near-miss:out-of-scope');
+});
+
+test('lists every decision the hook records', () => {
+ assert.deepStrictEqual([...DECISIONS].sort(), [
+ 'cap',
+ 'credit',
+ 'deny',
+ 'destructive-deny',
+ 'pass',
+ 'pass-checked',
+ 'pass-exempt',
+ 'pass-subagent',
+ 'routine-deny',
+ 'routine-readonly',
+ 'sibling',
+ 'trivial'
+ ]);
+});
+
+test('rejects events with the wrong shape', () => {
+ const good = metricsEvent(base);
+ assert.ok(isMetricsEvent(good));
+ for (const bad of [
+ null,
+ [],
+ { ...good, v: 2 },
+ { ...good, session: 'ABC' },
+ { ...good, decision: 'allow' },
+ { ...good, tool: 'Read' },
+ { ...good, reason: '/x' },
+ { ...good, class: 'a b' },
+ { ...good, questions: ['ok', '/x'] },
+ { ...good, sensitive: 'no' },
+ { ...good, ts: 5 }
+ ]) {
+ assert.strictEqual(isMetricsEvent(bad), false, JSON.stringify(bad));
+ }
+});
+
+test('appends one line per event in a single write and rotates past the cap', () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-metrics-lib-'));
+ try {
+ const file = path.join(dir, 'nested', METRICS_FILE_NAME);
+ assert.strictEqual(appendMetrics(path.dirname(file), [metricsEvent(base), null, metricsEvent({ ...base, decision: 'credit' })]), true);
+ assert.strictEqual(fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).length, 2);
+ fs.writeFileSync(`${file}.1`, 'old\n');
+ fs.writeFileSync(file, 'x'.repeat(METRICS_MAX_BYTES));
+ assert.strictEqual(appendMetrics(path.dirname(file), [metricsEvent(base)]), true);
+ assert.strictEqual(fs.statSync(`${file}.1`).size, METRICS_MAX_BYTES);
+ assert.strictEqual(fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).length, 1);
+ assert.strictEqual(appendMetrics(path.dirname(file), [null]), false);
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test('reports failure instead of throwing when the file cannot be written', () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-metrics-lib-'));
+ try {
+ fs.mkdirSync(path.join(dir, METRICS_FILE_NAME));
+ assert.strictEqual(appendMetrics(dir, [metricsEvent(base)]), false);
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+console.log(`\n ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/scripts/gateguard-report.test.js b/tests/scripts/gateguard-report.test.js
new file mode 100644
index 000000000..d2111a7b4
--- /dev/null
+++ b/tests/scripts/gateguard-report.test.js
@@ -0,0 +1,182 @@
+/**
+ * Tests for scripts/gateguard-report.js
+ */
+
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'gateguard-report.js');
+const FIXTURE_DIR = path.join(__dirname, '..', 'fixtures', 'gateguard-metrics');
+const { loadMetrics, summarize, formatReport, parseArgs } = require('../../scripts/gateguard-report');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${name}`);
+ passed++;
+ } catch (error) {
+ console.log(` ✗ ${name}`);
+ console.log(` Error: ${error.message}`);
+ failed++;
+ }
+}
+
+function run(args, env = {}) {
+ const result = spawnSync('node', [SCRIPT, ...args], {
+ encoding: 'utf8',
+ env: { ...process.env, ...env },
+ timeout: 10000
+ });
+ return { status: result.status, stdout: result.stdout || '', stderr: result.stderr || '' };
+}
+
+console.log('\n=== Testing gateguard-report ===\n');
+
+const loaded = loadMetrics(FIXTURE_DIR);
+const report = summarize(loaded.events);
+
+test('reads the rotated file first, then the current file', () => {
+ assert.strictEqual(loaded.events.length, 12);
+ assert.strictEqual(loaded.events[0].ts, '2026-09-01T10:00:00.000Z');
+ assert.strictEqual(loaded.events[11].decision, 'pass-checked');
+ assert.deepStrictEqual(loaded.files.map(f => path.basename(f)), ['metrics.jsonl.1', 'metrics.jsonl']);
+});
+
+test('skips malformed, unknown-version, unknown-decision and non-code lines', () => {
+ assert.strictEqual(loaded.skipped, 6);
+ assert.ok(loaded.events.every(e => e.session === 'aaaaaaaaaaaa' || e.session === 'bbbbbbbbbbbb'));
+ assert.ok(!loaded.events.some(e => String(e.reason).includes('/')));
+});
+
+test('counts decisions by type', () => {
+ assert.deepStrictEqual(report.total.decisions, {
+ deny: 4,
+ cap: 1,
+ credit: 1,
+ 'destructive-deny': 1,
+ 'pass-checked': 1,
+ 'routine-deny': 1,
+ 'routine-readonly': 1,
+ sibling: 1,
+ trivial: 1
+ });
+ assert.strictEqual(report.total.events, 12);
+});
+
+test('breaks denials down by class and reason', () => {
+ assert.strictEqual(report.total.denials.total, 6);
+ assert.deepStrictEqual(report.total.denials.byClass, { code: 3, shell: 2, config: 1 });
+ assert.deepStrictEqual(report.total.denials.byReason, {
+ 'first-touch': 2,
+ destructive: 1,
+ 'first-command': 1,
+ 'near-miss:out-of-scope': 1,
+ sensitive: 1
+ });
+});
+
+test('reports the near-miss share of first-touch denials', () => {
+ assert.deepStrictEqual(report.total.nearMiss, { count: 1, of: 4, share: 0.25 });
+});
+
+test('reports first-touch outcome rates', () => {
+ const { firstTouch } = report.total;
+ assert.strictEqual(firstTouch.total, 8);
+ assert.deepStrictEqual(firstTouch.counts, { deny: 4, credit: 1, sibling: 1, cap: 1, trivial: 1 });
+ assert.strictEqual(firstTouch.rates.deny, 0.5);
+ assert.strictEqual(firstTouch.rates.trivial, 0.125);
+});
+
+test('counts routine read-only passes and ranks the most-asked questions', () => {
+ assert.strictEqual(report.total.routineReadonlyPasses, 1);
+ assert.deepStrictEqual(report.total.topQuestions.slice(0, 3), [
+ ['quote-instruction', 4],
+ ['callers', 1],
+ ['config-effect', 1]
+ ]);
+});
+
+test('summarizes each session separately in order of first appearance', () => {
+ assert.deepStrictEqual(Object.keys(report.sessions), ['aaaaaaaaaaaa', 'bbbbbbbbbbbb']);
+ const a = report.sessions.aaaaaaaaaaaa;
+ assert.strictEqual(a.events, 6);
+ assert.strictEqual(a.denials.total, 3);
+ assert.deepStrictEqual(a.nearMiss, { count: 1, of: 2, share: 0.5 });
+ assert.strictEqual(a.firstTouch.total, 4);
+ assert.strictEqual(a.first, '2026-09-01T10:00:00.000Z');
+ assert.strictEqual(a.last, '2026-09-01T10:05:00.000Z');
+ const b = report.sessions.bbbbbbbbbbbb;
+ assert.strictEqual(b.events, 6);
+ assert.deepStrictEqual(b.denials.byClass, { code: 1, config: 1, shell: 1 });
+ assert.strictEqual(b.routineReadonlyPasses, 0);
+});
+
+test('reports empty rates as null instead of dividing by zero', () => {
+ const empty = summarize([]);
+ assert.strictEqual(empty.total.events, 0);
+ assert.strictEqual(empty.total.nearMiss.share, null);
+ assert.strictEqual(empty.total.firstTouch.rates.deny, null);
+});
+
+test('formats a readable text report', () => {
+ const text = formatReport({ ...loaded, report });
+ assert.ok(text.includes('12 events in 2 sessions (6 malformed lines skipped)'));
+ assert.ok(text.includes('Total'));
+ assert.ok(text.includes('Session aaaaaaaaaaaa'));
+ assert.ok(text.includes('near-miss share of first-touch denials: 25.0% (1 of 4)'));
+ assert.ok(text.includes('routine read-only passes: 1'));
+ assert.ok(text.includes('quote-instruction 4'));
+});
+
+test('parses --dir, --dir=, --json and --help', () => {
+ assert.deepStrictEqual(parseArgs(['--dir', '/x', '--json']), { dir: '/x', json: true, help: false });
+ assert.deepStrictEqual(parseArgs(['--dir=/y']), { dir: '/y', json: false, help: false });
+ assert.strictEqual(parseArgs(['-h']).help, true);
+ assert.throws(() => parseArgs(['--dir']), /Missing value for --dir/);
+ assert.throws(() => parseArgs(['--bogus']), /Unknown argument: --bogus/);
+});
+
+test('CLI prints JSON with --json', () => {
+ const result = run(['--dir', FIXTURE_DIR, '--json']);
+ assert.strictEqual(result.status, 0, result.stderr);
+ const parsed = JSON.parse(result.stdout);
+ assert.strictEqual(parsed.events, 12);
+ assert.strictEqual(parsed.skipped, 6);
+ assert.strictEqual(parsed.total.denials.total, 6);
+ assert.deepStrictEqual(Object.keys(parsed.sessions), ['aaaaaaaaaaaa', 'bbbbbbbbbbbb']);
+});
+
+test('CLI reads GATEGUARD_STATE_DIR when --dir is not given', () => {
+ const result = run([], { GATEGUARD_STATE_DIR: FIXTURE_DIR });
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(result.stdout.includes('12 events in 2 sessions'));
+});
+
+test('CLI explains how to enable metrics when none are found', () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-report-'));
+ try {
+ const result = run(['--dir', dir]);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(result.stdout.includes('No GateGuard metrics'));
+ assert.ok(result.stdout.includes('GATEGUARD_METRICS=1'));
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test('CLI exits 1 on an unknown argument', () => {
+ const result = run(['--bogus']);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('Unknown argument: --bogus'));
+});
+
+console.log(`\n ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.js
index 02ca28943..a63f7f0dc 100644
--- a/tests/scripts/npm-publish-surface.test.js
+++ b/tests/scripts/npm-publish-surface.test.js
@@ -83,6 +83,7 @@ function buildExpectedPublishPaths(repoRoot) {
"scripts/uninstall.js",
"scripts/welcome.js",
"scripts/gemini-adapt-agents.js",
+ "scripts/gateguard-report.js",
"scripts/sync-ecc-to-codex.sh",
"scripts/codex/legacy-sync-state.js",
"scripts/codex/install-global-git-hooks.sh",