feat(diagnostics): add structured diagnostic logger for agent executions

[snipcodeit]

Summary

• Created lib/agent-diagnostics.cjs — a non-blocking diagnostic logger for GSD agent executions
• Captures per-invocation telemetry: agent type, prompt hash, timestamps, turn count, exit reason, output size, and failure classification
• Writes diagnostic entries as JSON files to .mgw/diagnostics/<issue-number>-<timestamp>.json with 30-day auto-pruning
• Gracefully falls back through agent-errors.cjs -> retry.cjs -> minimal classification for failure typing

Closes #230

Milestone Context

• Milestone: v8 — Agent Reliability & Failure Recovery
• Phase: 44 — Agent Failure Taxonomy & Diagnostic Logging
• Issue: 2 of 9 in milestone

Changes

lib/ (core module)

• lib/agent-diagnostics.cjs (451 lines) — New module with 7 exports:
  • getDiagnosticsDir() — Directory management
  • createDiagnosticLogger() — Factory pattern for agent invocation tracking
  • writeDiagnosticEntry() — Low-level JSON entry writer
  • pruneDiagnostics() — 30-day retention enforcement
  • readDiagnostics() — Query with filters (issueNumber, agentType, since, limit)
  • shortHash() — SHA-256 utility for prompt hashing
  • DEFAULT_MAX_AGE_DAYS — Configurable retention constant

.planning/ (GSD artifacts)

• Plan, summary, and verification documents for quick task 8

Test Plan

• Module loads without errors (node -e "require('./lib/agent-diagnostics.cjs')")
• All 7 exports verified present and typed correctly
• Write/read round-trip for diagnostic entries
• Logger factory start/finish pattern works end-to-end
• Error classification fallback path confirmed (agent-errors.cjs not yet on main)
• Prune function correctly skips recent entries, would remove old ones
• Non-blocking: null inputs and invalid paths return safe defaults, never throw
• Filter functionality verified: issueNumber, agentType, limit
• 19/19 functional assertions passed

[snipcodeit]

Testing Procedures

Quick Verification

node -e "const d = require('./lib/agent-diagnostics.cjs'); console.log(Object.keys(d))"

Expected output: getDiagnosticsDir, createDiagnosticLogger, writeDiagnosticEntry, pruneDiagnostics, readDiagnostics, shortHash, DEFAULT_MAX_AGE_DAYS

Functional Test

const diag = require('./lib/agent-diagnostics.cjs');

// 1. Create and use a logger
const logger = diag.createDiagnosticLogger({
  agentType: 'gsd-executor',
  issueNumber: 999,
  promptHash: diag.shortHash('test prompt'),
});
logger.start();
// simulate work...
logger.finish({ exitReason: 'success', turnCount: 10, outputSize: 2048 });

// 2. Read back
const entries = diag.readDiagnostics({ issueNumber: 999 });
console.log(entries); // Should show 1 entry

// 3. Prune (nothing to remove)
console.log(diag.pruneDiagnostics()); // { removed: 0, errors: 0, total: N }

// 4. Error handling
const errorLogger = diag.createDiagnosticLogger({ agentType: 'gsd-verifier', issueNumber: 998 });
errorLogger.start();
errorLogger.finish({ exitReason: 'error', error: new Error('agent timed out') });
const errEntries = diag.readDiagnostics({ issueNumber: 998 });
console.log(errEntries[0].failure_classification); // Should be non-null

Non-Blocking Verification

// These should all return safe defaults, never throw
diag.writeDiagnosticEntry(null);         // false
diag.readDiagnostics({ repoRoot: '/x' }); // []
diag.pruneDiagnostics({ repoRoot: '/x' }); // { removed: 0, errors: 0, total: 0 }